Skip to main content
When you bring several clusters you already run into Ankra, describe each one in its own ImportCluster file and let a CI job apply them. You end up with one repository that says what every cluster runs, a check on every change, and an apply on every merge. Allow an hour for the first two clusters. This guide uses ankra cluster apply from CI. Two other routes exist, and a cluster should use only one of them:
  • A GitOps repository connected to the cluster. Ankra then reads the cluster’s definition from that repository on every sync, and you edit the files in the cluster’s directory instead of applying them. See GitOps.
  • Terraform. The ankra_cluster resource registers a cluster you operate and keeps its Stacks in Terraform. See Ankra Terraform Provider.

Before you start

  • A service token for the CI job, with a role that may add and change clusters, stored as the CI secret ANKRA_API_TOKEN. See Service Tokens.
  • A payment method on the organisation, because the first apply of a file creates the cluster. See Billing.
  • Helm and a kubeconfig for each new cluster, on the machine where you install its agent.
  • A default StorageClass on each cluster if its Stacks hold volumes. See Set up storage on a cluster you connect.
  • The Ankra CLI:

Steps

1

Write one file per cluster

Keep one file per cluster, named after it, such as clusters/staging.yaml and clusters/production.yaml. metadata.name is the cluster’s name in Ankra, so it must differ between files. metadata.environment says what the cluster is for. Put each file’s values and manifests next to it: from_file paths resolve against the directory the file is in. Every field is in the ImportCluster YAML Schema.
For a cluster that is already in Ankra, start from its current definition with ankra cluster export --cluster <cluster-name> -f clusters/<cluster-name>.yaml. The export carries no manifest bodies and no add-on values, so give each manifest and add-on its content before you apply the file.Check: ankra cluster apply -f clusters/staging.yaml --dry-run prints Validation succeeded for "clusters/staging.yaml"; no changes applied (--dry-run).
2

Validate every change in CI

On every pull request, run the server-side check for each file. It runs every rule an apply enforces without touching a cluster: duplicate names, parents, cycles, charts and versions that exist, plaintext secrets and field rules.
--strict-secrets turns a plaintext secret into an error instead of a warning. Once a cluster exists, add --cluster <cluster-name> to validate against its live resources too.Check: the job fails on a file with a mistake and passes on the others.
3

Apply a new cluster once from your terminal

The first apply of a file creates the cluster. Run it yourself, with --wait, so you get the agent install command:
The CLI prints Cluster 'staging' imported! and, under To install the Ankra agent, run:, a helm upgrade --install command. Run that command with your kubeconfig pointing at the new cluster.
The install command carries the cluster’s agent token. Run the first apply from your terminal, not from CI, so the token never lands in a CI log, and do not commit the command.
Check: the cluster’s status in Clusters turns online within about a minute, and ankra cluster operations list --cluster staging shows its Stacks deploying.
4

Apply from CI on merge

On every merge to the default branch, apply each file:
For an existing cluster the CLI prints Cluster '<name>' configuration applied. --wait covers the configuration write only: add-on and manifest deploys run afterwards. Follow them with ankra cluster operations list --cluster <cluster-name>.To run this job on Ankra Pipelines, see Ankra Pipelines.Check: the job’s log shows configuration applied for each cluster, and each cluster’s operations list shows the deploys finishing.

Keep the files and the clusters in step

The files are the only route of change for the Stacks they declare. An apply replaces each Stack the file names with what the file says.
  • A member removed from a file is not removed silently. An apply whose file no longer lists an add-on, manifest or application of its Stacks is refused and changes nothing. The CLI prints: If these should go, apply again with --confirm-removal <kind>/<name>, or with --prune when the file is the complete, current definition of its stacks. Otherwise add them to the file.
  • A member someone added in the portal shows up the same way. It is not in the file, so the next apply from CI is refused and names it. Add it to the file, or confirm its removal.
  • Renaming a manifest deletes its resources. A manifest’s name is its identity; see the warning under spec.stacks[].manifests[] before you rename one that owns a namespace or volumes.
--prune removes every member the file no longer lists, with the resources they own. Use it in CI only when each file is the complete, current definition of its Stacks.

What can go wrong

  • For a new cluster, the agent install command is only shown when you use --wait. The apply ran without --wait. Create the install command in the portal under Infrastructure → Clusters → <your cluster> → Settings → Upgrades and maintenance → Agent install command, or apply again with --wait.
  • Import failed with the following issues: The CLI lists each resource and the field the platform refused. Fix the file and apply again; ankra cluster validate catches the same errors before a merge.
  • An apply is refused for members the file does not list. See Keep the files and the clusters in step.
  • metadata.environment did not change an existing cluster. A file sets the environment only where nobody has chosen one. The CLI prints the ankra cluster update command that changes it.

Where to go next