Ankra Terraform Provider

​

Configure the provider

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

provider "ankra" {}

​

Resources and data sources

​

Create a cluster on your cloud

resource "ankra_hetzner_cluster" "dev" {
  name          = "my-cluster"
  credential_id = "<hetzner-credential-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"
  }
}

ankra credentials list
ankra credentials hetzner ssh-key list

​

Register a cluster you already run

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 = "traefik"
      registry_url  = "https://traefik.github.io/charts"
      namespace     = "traefik"
      parents       = ["manifest:traefik-namespace"]

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

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

• 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. 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; otherwise Ankra asks you to connect the registry first. Set registry_credential_name for a private registry.
• 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.

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

​

List clusters

data "ankra_clusters" "all" {}

output "cluster_names" {
  value = [for cluster in data.ankra_clusters.all.clusters : cluster.name]
}

​

Import existing clusters

terraform import ankra_cluster.prod <cluster-id>
terraform import ankra_hetzner_cluster.dev <cluster-id>

​

Readiness and timeouts

​

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 are not detected. Ankra’s cluster listing does not include node counts or sizes, so a plan cannot see them.
• No managed Kubernetes and no node groups. See Resources and data sources.

​

Upgrade from 0.1.x

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 now 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.

​

Next steps