Terraform Provider Reference

Manage Admiral resources as infrastructure-as-code with the Terraform provider: create applications, configure environments, and fold it into your pipelines.

The Admiral Terraform provider lets you declare and manage Admiral resources as part of your infrastructure-as-code workflows. Use it to create applications and their environments, and to integrate Admiral into your existing Terraform pipelines.

Resource and data source schemas are generated from the provider itself and published on the Terraform Registry, which is the source of truth for the current release.

Installation

Add the provider to your Terraform configuration:

terraform {
  required_version = ">= 1.0"

  required_providers {
    admiral = {
      source  = "admiral-io/admiral"
      version = "~> 0.2"
    }
  }
}

Then run:

terraform init

Provider configuration

provider "admiral" {
  api_key = var.admiral_api_key
}

Attribute	Type	Required	Default	Description
`server`	String	No	`api.admiral.io:443`	Admiral API address as `host:port`. Port 443 is appended if omitted. Also reads `ADMIRAL_SERVER`
`api_key`	String	Yes	none	API key (sensitive). Also reads `ADMIRAL_API_KEY`
`insecure`	Boolean	No	`false`	Connect over TLS without verifying the server certificate
`plaintext`	Boolean	No	`false`	Connect without TLS. The key travels unencrypted; only for a local server

The attribute names and environment variables match the CLI, so a shell set up for admiral is already set up for Terraform. API keys are created in the console; see CLI reference for how they are used from CI.

Using environment variables

For CI/CD and shared configurations, set credentials via environment variables instead of hardcoding them:

export ADMIRAL_API_KEY="admp_..."

# No explicit api_key needed when the env var is set
provider "admiral" {}

Example usage

Create an application

resource "admiral_application" "payments" {
  name        = "payment-service"
  description = "Payment processing microservice"

  labels = {
    team = "backend"
    tier = "critical"
  }
}

output "app_id" {
  value = admiral_application.payments.id
}

Add environments

An environment belongs to an application. Its name is unique within that application, and changing application_id replaces the environment.

resource "admiral_environment" "staging" {
  application_id = admiral_application.payments.id
  name           = "staging"
}

resource "admiral_environment" "production" {
  application_id = admiral_application.payments.id
  name           = "production"
  description    = "Customer-facing"

  labels = {
    tier = "critical"
  }
}

Look up existing resources

# An application, by name or by ID
data "admiral_application" "existing" {
  name = "payment-service"
}

data "admiral_application" "by_id" {
  id = "550e8400-e29b-41d4-a716-446655440000"
}

# An environment, by application and name, or by ID
data "admiral_environment" "production" {
  application_id = data.admiral_application.existing.id
  name           = "production"
}

data "admiral_environment" "by_id" {
  id = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}

Manage multiple applications

variable "applications" {
  type = map(object({
    description  = string
    labels       = map(string)
    environments = set(string)
  }))
  default = {
    "auth-service" = {
      description  = "Authentication and authorization"
      labels       = { team = "platform", tier = "critical" }
      environments = ["staging", "production"]
    }
    "api-gateway" = {
      description  = "Public API gateway"
      labels       = { team = "platform", tier = "critical" }
      environments = ["staging", "production"]
    }
    "worker" = {
      description  = "Background job processing"
      labels       = { team = "backend", tier = "standard" }
      environments = ["production"]
    }
  }
}

resource "admiral_application" "apps" {
  for_each = var.applications

  name        = each.key
  description = each.value.description
  labels      = each.value.labels
}

locals {
  environments = {
    for pair in flatten([
      for app, cfg in var.applications : [
        for env in cfg.environments : { app = app, env = env }
      ]
    ]) : "${pair.app}/${pair.env}" => pair
  }
}

resource "admiral_environment" "envs" {
  for_each = local.environments

  application_id = admiral_application.apps[each.value.app].id
  name           = each.value.env
}

Import existing resources

Import an application or environment into Terraform state using its UUID:

terraform import admiral_application.payments 550e8400-e29b-41d4-a716-446655440000
terraform import admiral_environment.production 6ba7b810-9dad-11d1-80b4-00c04fd430c8

Terraform Provider