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_clusterresource 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 For a cluster that is already in Ankra, start from its current definition with
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.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 The CLI prints
--wait, so you get the agent install command: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.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.
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 validatecatches 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.environmentdid not change an existing cluster. A file sets the environment only where nobody has chosen one. The CLI prints theankra cluster updatecommand that changes it.
Where to go next
- Bring an existing cluster under Ankra for storage, GitOps, kubectl access and backups on each cluster.
- ImportCluster YAML Schema for every field.
- Backups and Restore Points to protect the stateful Stacks your files declare.