Ankra Terraform Provider

Manage Ankra from Terraform with the ankraio/ankra provider - clusters on every cloud, managed Kubernetes, node groups, credentials, Helm registries, variables, cluster settings, alerts and DNS, applications and pipelines, stack profiles, backups, members and tokens, plus projects, import, readiness waits, known limits and upgrading.

You manage your infrastructure with Terraform and want Ankra in the same plan. The Ankra Terraform provider, ankraio/ankra on the Terraform Registry, manages what the Ankra CLI can create, change or delete: clusters on your cloud, managed Kubernetes, node groups, credentials, Helm registries, variables, alerts, DNS, applications, pipelines, stack profiles, backups, members, tokens and organisation settings. The Registry carries the generated reference for every resource and attribute.

This page describes provider 0.3.0, which brings the provider to parity with the CLI: 97 resources and 42 data sources. On 0.2.x only the six cluster resources and the ankra_clusters data source exist. Check the version you can install on the Registry before you use a resource from What you can manage, and read Upgrade from 0.2.x before you upgrade.

Configure the provider

The provider needs Terraform 1.0 or newer (it is tested with 1.6 to 1.12).

terraform {
  required_providers {
    ankra = {
      source  = "ankraio/ankra"
      version = "~> 0.3.0"
    }
  }
}

provider "ankra" {
  project_id = var.ankra_project_id
}

variable "ankra_project_id" {
  type = string
}

Argument	Environment variable	Notes
token	ANKRA_TOKEN	An Ankra API token. Prefer the environment variable so the token stays out of your configuration.
base_url	ANKRA_BASE_URL	Defaults to https://platform.ankra.app.
organisation_id	ANKRA_ORG	Act in another organisation your user belongs to, like the CLI’s --org flag, which reads the same variable. Takes the organisation’s ID, not its name. Defaults to the organisation the token belongs to.
project_id	ANKRA_PROJECT_ID	The project to act in, for organisations that group their clusters and resources into projects. Takes the project’s ID. Required in an organisation with more than one project.

If no token reaches a resource, from the provider or the deprecated per-resource ankra_token, Terraform stops with Missing API token and sends no request.

Projects and organisations

Without project_id, Ankra scopes every request to the project your user last selected in the UI, so switching project there would change what Terraform sees. The resources added in 0.3.0 therefore refuse to run in an organisation with more than one project until the provider sets project_id, and they send nothing until it does.

When organisation_id or project_id changes, an object Terraform created in the old scope is reported as not visible in the provider’s current scope. It is not planned for recreation, and terraform destroy does not report it destroyed while it still exists. Point the provider back at the old scope to manage it, or run terraform state rm to stop managing it.

If organisation_id or project_id is only known after apply (for example, it comes from another resource), the provider sends no request until it is known instead of acting in your default organisation or project.

What you can manage

Each name links to its reference on the Registry through the provider’s documentation index.

Area	Resources	Data sources
Clusters Ankra builds	ankra_hetzner_cluster, ankra_digitalocean_cluster, ankra_ovh_cluster, ankra_upcloud_cluster, ankra_scaleway_cluster (Closed Beta), ankra_aws_cluster, ankra_proxmox_cluster, ankra_morpheus_cluster, ankra_ankracloud_cluster, ankra_playground	ankra_clusters, ankra_cluster, ankra_kubernetes_versions, ankra_playground_plans
Managed Kubernetes	ankra_managed_cluster, ankra_managed_node_pool
Node groups	ankra_node_group	ankra_node_groups
Clusters you run	ankra_cluster
Credentials	ankra_hetzner_credential, ankra_digitalocean_credential, ankra_upcloud_credential, ankra_ovh_credential, ankra_scaleway_credential, ankra_azure_credential, ankra_ankracloud_credential, ankra_morpheus_credential, ankra_proxmox_credential, ankra_aws_role_credential, ankra_aws_keys_credential, ankra_ssh_key_credential	ankra_credentials, ankra_credential
Helm registries and variables	ankra_helm_registry, ankra_helm_registry_credential, ankra_organisation_variable, ankra_cluster_variable	ankra_helm_registries, ankra_helm_registry_credentials, ankra_helm_chart, ankra_organisation_variables, ankra_cluster_variables
Cluster settings	ankra_cluster_access_grant, ankra_cluster_ssh_keys, ankra_cluster_custom_dns_zone, ankra_cluster_power_schedule, ankra_cluster_agent_auto_upgrade, ankra_cluster_agent_ci_settings, ankra_cluster_log_shipping, ankra_cluster_mesh, ankra_cluster_mesh_member	ankra_cluster_access_grants, ankra_cluster_custom_dns_zones, ankra_cluster_power_schedules, ankra_cluster_meshes
Alerts and DNS	ankra_alert_destination, ankra_alert_route, ankra_organisation_dns_record, ankra_organisation_custom_dns_zone, ankra_organisation_domain, ankra_dns_credential, ankra_cloudflare_credential, ankra_cloudflare_dns_record	ankra_alert_destinations, ankra_alert_routes, ankra_organisation_dns_zone, ankra_organisation_dns_records, ankra_organisation_custom_dns_zones, ankra_dns_credentials, ankra_cloudflare_credentials, ankra_cloudflare_domains
Applications and pipelines	ankra_application, ankra_application_settings, ankra_application_auto_deploy, ankra_application_ai_config, ankra_application_demo_config, ankra_application_env_secret, ankra_application_deployment, ankra_pipeline_repository, ankra_pipeline_definition, ankra_pipeline_schedule, ankra_pipeline_merge_train	ankra_applications, ankra_application, ankra_pipeline_repositories
Stack profiles, backups and the image registry	ankra_stack_profile, ankra_stack_profile_version, ankra_stack_profile_share, ankra_stack_profile_logo, ankra_backup_vault, ankra_object_storage_bucket, ankra_registry_project, ankra_registry_robot, ankra_registry_retention	ankra_stack_profiles, ankra_backup_vaults, ankra_object_storage_buckets, ankra_registry_projects, ankra_registry_robots
Organisation and access	ankra_organisation, ankra_organisation_member, ankra_api_token, ankra_service_token, ankra_mcp_server, ankra_mcp_tool_grant, ankra_ci_settings, ankra_ci_pool_member, ankra_ai_review_repository, ankra_ai_review_related_repository, ankra_ai_spend_cap, ankra_ai_environment	ankra_organisation, ankra_organisations, ankra_mcp_servers
AI, cost, security, services and hosts	ankra_ai_provider, ankra_ai_anthropic_key, ankra_ai_openrouter_key, ankra_ai_openai_compatible, ankra_ai_endpoint, ankra_ai_model, ankra_ai_lane_model, ankra_ai_board_identity, ankra_cost_budget, ankra_cost_autopilot, ankra_cost_autopilot_override, ankra_cost_settings, ankra_security_disposition, ankra_security_compliance_framework, ankra_security_report_schedule, ankra_service_placement_policy, ankra_service_consumer, ankra_host_join_token	ankra_ai_models, ankra_ai_endpoints, ankra_ai_lanes, ankra_cost_budgets, ankra_security_compliance_frameworks, ankra_host_targets, ankra_deploy_environments

Operational commands stay in the CLI: logs, exec, metrics, pipeline runs and reruns, cluster scale, cluster upgrade, chat and the AI board. Stack variables, managed services, stack profile drafts, restore points and migrations have no Terraform resource either.

Create a cluster on your cloud

The cloud cluster resources share most arguments and each keeps its cloud’s own words for size and place.

resource "ankra_hetzner_credential" "main" {
  name      = "hetzner-main"
  api_token = var.hcloud_token
}

resource "ankra_hetzner_cluster" "dev" {
  name          = "my-cluster"
  credential_id = ankra_hetzner_credential.main.id
  location      = "fsn1"

  control_plane_count       = 1
  control_plane_server_type = "cpx22"
  worker_count              = 2
  worker_server_type        = "cpx22"
  bastion_server_type       = "cpx12"

  gitops_repository      = "my-org/my-repo"
  gitops_branch          = "main"
  gitops_credential_name = "my-github-credential"

  timeouts {
    create = "60m"
  }
}

variable "hcloud_token" {
  type      = string
  sensitive = true
}

Required arguments:

Resource	Required
ankra_hetzner_cluster	name, credential_id, location
ankra_digitalocean_cluster	name, credential_id, ssh_key_credential_id, region
ankra_ovh_cluster	name, credential_id, ssh_key_credential_id, region
ankra_upcloud_cluster	name, credential_id, ssh_key_credential_id, zone
ankra_scaleway_cluster	name, credential_id, ssh_key_credential_id, region, zone

AWS, Proxmox, Morpheus and Ankra Cloud follow the same pattern; their Registry pages list each one’s required arguments.

Optional arguments every cloud resource takes:

Argument	Notes
ssh_key_credential_id	Optional on Hetzner. The ID of an SSH key credential, for example ankra_ssh_key_credential.<name>.id.
distribution, cni	kubeadm and cilium by default. For k3s set distribution = "k3s" and cni to flannel or calico.
kubernetes_version	Defaults to the platform’s stable version. data.ankra_kubernetes_versions lists the others.
control_plane_count, worker_count, and the per-role size arguments	Node counts and machine sizes: server_type on Hetzner, size on DigitalOcean, flavor_id on OVHcloud, plan on UpCloud, type on Scaleway.
etcd_topology, etcd_node_count	stacked or external etcd on kubeadm clusters.
include_networking	Install Traefik and cert-manager.
external_cloud_provider	Install the cloud controller manager and CSI driver.
gitops_repository, gitops_branch, gitops_credential_name	Commit the generated Stack to your GitOps repository.
wait_for_ready, timeouts	See Readiness and timeouts.
force_destroy	See below.

A cluster’s own provisioning arguments force replacement: change worker_count or a size on the cluster resource and the plan destroys and recreates the cluster. To add capacity, add or change an ankra_node_group, or scale with the CLI or the UI. Read every plan before you apply it.

terraform destroy asks Ankra to deprovision the cluster and remove what it created in your cloud account, and on AWS, Proxmox, Morpheus and Ankra Cloud it waits until the cluster is gone. force_destroy skips the platform’s usual guards: it is true by default on Hetzner, DigitalOcean, OVHcloud, UpCloud and Scaleway and false on the others. On AWS and Ankra Cloud, Ankra refuses to delete a cluster that still holds persistent volumes unless you set accept_volume_data_loss = true.

Closed beta. Scaleway as a cluster provider is in closed beta, and ankra_scaleway_cluster only works for organisations that have it turned on. Until it is, the Scaleway endpoints are not served and the create fails. Contact support to have it turned on for your organisation.

To use credentials you already created, find their IDs with the CLI. The ID column of ankra credentials list holds credential_id, and the provider’s ssh-key list holds ssh_key_credential_id:

ankra credentials list
ankra credentials hetzner ssh-key list

Node groups

ankra_node_group adds a group of workers to a cluster Ankra built. node_count, instance_type, labels, taints and autoscaling change in place. An instance_type change drains and power-cycles each node, and the apply waits until every node is back on the new type.

resource "ankra_node_group" "gpu" {
  cluster_id    = ankra_hetzner_cluster.dev.cluster_id
  name          = "gpu"
  instance_type = "cx42"
  node_count    = 2

  labels = {
    accelerator = "gpu"
  }

  timeouts {
    create = "30m"
    update = "30m"
  }
}

Managed Kubernetes

ankra_managed_cluster creates a cluster on DigitalOcean (DOKS), UpCloud (UKS), Google (GKE), Azure (AKS), AWS (EKS), OVHcloud (MKS), Scaleway (Kapsule) or Ankra Cloud Kubernetes and connects it to Ankra. Options specific to one provider go in provider_options.

resource "ankra_managed_cluster" "aks" {
  provider_name = "aks"
  name          = "aks-prod"
  credential_id = var.azure_credential_id
  location      = "westeurope"

  provider_options = jsonencode({
    resource_group = "rg-ankra"
  })

  node_pools = {
    system = {
      size       = "Standard_D4s_v5"
      node_count = 3
    }
  }
}

variable "azure_credential_id" {
  type = string
}

node_pools is a map keyed by pool name. node_count and autoscaling change in place, adding a key adds a pool and removing one deletes it. To change a pool’s size, give it a new key: the new pool is added, and the old one is deleted only after the new pool’s nodes are ready. Ankra cannot check pool readiness on UKS and OVHcloud MKS, so there both pools are kept and the apply stops with an explanation. Other changes to an existing pool are refused at plan time. ankra_managed_node_pool manages a pool outside the cluster resource.

destroy_mode decides what terraform destroy does: delete_provider_cluster deletes the cluster at the provider, disconnect only removes it from Ankra. Clusters this resource created default to deleting, imported ones to disconnecting. wait_for_agent = true waits until the Ankra agent is online.

Register a cluster you already run

ankra_cluster registers a cluster you operate yourself, the same way an ImportCluster file does, and keeps its Stacks in Terraform.

resource "ankra_helm_registry" "traefik" {
  name = "traefik"
  url  = "https://traefik.github.io/charts"
}

resource "ankra_cluster" "prod" {
  cluster_name           = "my-cluster"
  github_credential_name = "my-github-credential"
  github_repository      = "my-org/my-repo"
  github_branch          = "main"

  stacks {
    name        = "ingress"
    description = "Traefik ingress controller"

    manifests {
      name = "traefik-namespace"
      manifest_base64 = base64encode(<<-YAML
        apiVersion: v1
        kind: Namespace
        metadata:
          name: traefik
        YAML
      )
    }

    addons {
      name          = "traefik"
      chart_name    = "traefik"
      chart_version = "37.1.1"
      registry_name = ankra_helm_registry.traefik.name
      registry_url  = ankra_helm_registry.traefik.url
      namespace     = "traefik"
      parents       = ["manifest:traefik-namespace"]

      configuration = <<-YAML
        deployment:
          replicas: 2
        YAML

      job_configuration = jsonencode({
        create_job_timeout = 600
      })
    }
  }
}

Argument	Notes
cluster_name	Required. Changing it replaces the cluster.
github_credential_name, github_repository, github_branch	Required. The cluster’s GitOps repository. See Known limits before changing them.
stacks	name, description, manifests and addons.
manifests	name and either manifest_base64 (the manifest, base64-encoded) or from_file; optional namespace and parents.
addons	name, chart_name, chart_version, namespace, and registry_url (or its deprecated alias repository_url); optional registry_name, registry_credential_name, configuration, job_configuration and parents.
wait_for_online	false by default. See Readiness and timeouts.

How the Stack fields work:

• parents orders deployment. Write each entry as "manifest:<name>" or "addon:<name>". A bare "<name>" works when exactly one manifest or add-on of that name is declared in the resource. Leaving parents out keeps the order already stored in Ankra; an empty list removes it.
• registry_url is the Helm repository that serves the chart (https://... or oci://...). registry_name is the name of that Helm registry in your organisation, which ankra_helm_registry can create. If you leave it out, the provider derives a name from the URL, which Ankra accepts when a registry with that URL is already connected. Set registry_credential_name (an ankra_helm_registry_credential) for a private registry. data.ankra_helm_chart gives the latest_version of a chart if you want to pin to it.
• configuration holds the Helm values, as YAML or base64-encoded YAML.
• job_configuration is a JSON object of timeouts in seconds: create_job_timeout, read_job_timeout, update_job_timeout and delete_job_timeout. Build it with jsonencode.
• Stack variables you set in the UI or the CLI are kept when the resource applies the Stack.

The provider checks parents and job_configuration at plan time. If Ankra refuses the Stack, the error names the member and the field.

Attribute	Notes
cluster_id	The Ankra cluster ID.
helm_command	Installs the Ankra agent in the cluster. It contains a live agent token, so it is marked sensitive. Ankra issues it only when the cluster is first registered.
state, kind	As Ankra reports them. state is offline until the agent checks in, then online.

Run helm_command against the cluster to connect it. Terraform cannot run it inside the cluster for you, but a remote-exec provisioner on a host that can reach the cluster can:

resource "null_resource" "install_agent" {
  provisioner "remote-exec" {
    connection {
      type        = "ssh"
      host        = var.host
      user        = var.user
      private_key = file(var.private_key)
    }

    inline = [ankra_cluster.prod.helm_command]
  }
}

variable "host" {
  type = string
}

variable "user" {
  type = string
}

variable "private_key" {
  type = string
}

To run it yourself instead, expose it as a sensitive output and read it with terraform output -raw agent_install_command:

output "agent_install_command" {
  value     = ankra_cluster.prod.helm_command
  sensitive = true
}

If a cluster with the same cluster_name already exists, creating the resource adopts it: Ankra updates that cluster with your configuration and Terraform manages it from then on. Because the agent command is only issued on first registration, helm_command is empty for an adopted cluster, and Terraform prints a warning saying so. Copy the command from the Ankra UI if you need it.

terraform destroy deletes the cluster from Ankra.

Secrets, tokens and settings

• Secrets are write-only. API tokens, keys, passwords and webhook URLs are marked sensitive, and Ankra never returns them, so a secret changed outside Terraform is not detected. Terraform state still holds the value you configured, so keep state in an encrypted backend. On Terraform 1.11 and newer, ankra_application_env_secret takes value_wo, which is never stored in state.
• Values shown once (the token of ankra_api_token and ankra_service_token, a registry robot’s secret, a generated SSH private key, ankra_host_join_token) are captured into state when they are created.
• Changing a token’s expiry, scopes, label or project mints a new token value. The provider creates the new token before it removes the old one, so there is no gap, but every holder needs the new value. An empty scopes list is refused because Ankra reads it as full access. A member’s or service account’s role is changed in the UI, not in Terraform.
• Settings resources (ankra_ci_settings, ankra_ai_environment, ankra_ai_spend_cap, ankra_cluster_agent_ci_settings, ankra_cost_settings, ankra_cost_autopilot) write only the attributes you set and reset only those on destroy. Some refuse to create over settings already changed in the UI; import those instead.
• Applications. Creating ankra_application opens a setup pull request on its repository, which Ankra merges for you if ankra_application_settings.auto_merge_setup_pull_requests is on. Replacing an application removes every deployment of it, so consider lifecycle { prevent_destroy = true }. ankra_pipeline_definition is for repositories without a committed .ankra/pipeline.yaml.
• Data protection. The plan refuses a change that would replace a backup vault or bucket while destroy_provider_resources = true, because the replacement would delete its data.

Import existing objects

Every resource imports, most by their Ankra ID and cluster-scoped ones by <cluster_id>/<key>. Each resource’s Registry page shows its import ID.

terraform import ankra_cluster.prod <cluster-id>
terraform import ankra_hetzner_cluster.dev <cluster-id>
terraform import ankra_managed_cluster.aks aks/<cluster-id>
terraform import ankra_cluster_variable.domain <cluster-id>/ingress_domain

Ankra does not return a cluster’s build arguments or a credential’s secrets, so after an import the first apply adopts the values in your configuration as an in-place update instead of replacing the object. Write a configuration that matches the real object before you apply, and read the plan. ankra_host_join_token cannot be imported.

Readiness and timeouts

Resource	Waits for	Default timeouts
Cloud cluster resources	The cluster to reach running. Set wait_for_ready = false to return as soon as Ankra accepts the request.	create 60 minutes, delete 30 minutes
ankra_managed_cluster	The provider’s cluster, and with wait_for_agent = true the Ankra agent. A pool rename waits for the new pool.	update 30 minutes; set create and delete in timeouts
ankra_node_group	Each change, until the group’s nodes reflect it.	Set create, update and delete in timeouts
ankra_cluster	Registration. Set wait_for_online = true to also wait for the agent to check in, which only happens after someone runs helm_command.	create 60 minutes, update 20 minutes
ankra_application_deployment	The application’s setup to complete.	create 30 minutes

Keep the wait on when anything in the same plan uses the cluster, such as a kubeconfig, a kubernetes provider or a module, because provisioning runs in the background. The cluster ID is saved to state before the wait starts, so a timeout reports how far the cluster got without losing track of it.

Known limits

• Changing github_repository or github_branch on an existing ankra_cluster fails with a 409 error. Ankra refuses to move a cluster to a different GitOps source until the move is acknowledged, and the provider has no argument for that yet. Make the move outside Terraform as described under spec.git_repository in the ImportCluster reference, then update your configuration to match.
• helm_command is empty for an adopted cluster, and when Ankra queued the import instead of running it.
• Resizes made outside Terraform to a cluster’s own arguments are not detected. Node groups and managed node pools do refresh.
• Secrets changed outside Terraform are not detected. See Secrets, tokens and settings.
• Stack variables cannot be managed from Terraform yet. Use cluster or organisation variables, or the Stack itself.

Keep each object managed from one place, so Terraform, the CLI and the UI do not overwrite each other’s changes.

Upgrade from 0.2.x

1. Set project_id on the provider if your organisation uses projects. See Projects and organisations.
2. Imports of the original five cloud clusters now adopt your configuration on the first apply instead of planning a rebuild. Make the configuration match the real cluster first.
3. Read the first plan. Plan-time checks are stricter: values Ankra would refuse at apply now fail the plan instead.

Upgrade from 0.1.x

0.1.6 cannot create or update a cluster against the current Ankra API, so upgrade before you use the provider. Before you run terraform init -upgrade:

1. Pin distribution and cni on cloud resources. Both now default to kubeadm and cilium, and both force replacement. If a cluster was created with the old k3s and flannel defaults, add distribution = "k3s" and cni = "flannel" first, or the next plan replaces it.
2. Use Terraform 1.0 or newer. The provider runs on Terraform plugin protocol 6.
3. Move the token to the provider. Set token on the provider block or ANKRA_TOKEN. The per-resource ankra_token still works but is deprecated, and changing it no longer replaces the cluster.
4. Update add-ons. Replace repository_url with registry_url (the old name still works) and add registry_name. Write job_configuration as jsonencode({ ... }). configuration_type is ignored.
5. Update parents. Use "manifest:<name>" or "addon:<name>", or a bare name that matches exactly one member of the resource.
6. Rotate agent tokens printed by 0.1.x. helm_command contains a live agent token and 0.1.x did not mark it sensitive. If a plan or CI log printed it, rotate that token.

Then run terraform plan and check it reports no replacement you did not expect.

The full list of changes is in the provider’s changelog.

Next steps

Create an API token, find your project’s ID, and add the provider block above to your configuration. Start with a credential and a cluster, then move the rest of your organisation’s setup into the same plan.