---
title: "Terraform Provider"
canonical: "https://admiral.io/docs/reference/terraform-provider"
description: "Manage Admiral resources as infrastructure-as-code with the Terraform provider: create applications, configure environments, and fold it into your pipelines."
---

# Terraform Provider

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.

> **Note:** Resource and data source schemas are generated from the provider itself and published on the [Terraform Registry](https://registry.terraform.io/providers/admiral-io/admiral/latest/docs), which is the source of truth for the current release.

## Installation [#installation]

Add the provider to your Terraform configuration:

```hcl
terraform {
  required_version = ">= 1.0"

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

Then run:

```bash
terraform init
```

## Provider configuration [#provider-configuration]

```hcl
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](https://admiral.io/docs/reference/cli.md), so a shell set up for `admiral` is already set up for Terraform. API keys are created in the console; see [CLI reference](https://admiral.io/docs/reference/cli.md) for how they are used from CI.

### Using environment variables [#using-environment-variables]

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

```bash
export ADMIRAL_API_KEY="admp_..."
```

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

## Example usage [#example-usage]

### Create an application [#create-an-application]

```hcl
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 [#add-environments]

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

```hcl
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 [#look-up-existing-resources]

```hcl
# 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 [#manage-multiple-applications]

```hcl
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-existing-resources]

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

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

## Further reading [#further-reading]

* [Terraform Registry](https://registry.terraform.io/providers/admiral-io/admiral/latest/docs). Published provider with generated resource and data source documentation.
* [Provider source](https://github.com/admiral-io/terraform-provider-admiral). Issues, releases and contributing.