> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Import several clusters as code

> Keep one ImportCluster file per cluster in a repository, validate every change in CI, apply on merge, and keep the files and the clusters in step.

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](https://docs.ankra.ai/concepts/gitops.md).
* **Terraform.** The `ankra_cluster` resource registers a cluster you operate and keeps its Stacks in Terraform. See [Ankra Terraform Provider](https://docs.ankra.ai/integrations/terraform.md).

## 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](https://docs.ankra.ai/guides/service-tokens.md).
* **A payment method** on the organisation, because the first apply of a file creates the cluster. See [Billing](https://docs.ankra.ai/platform/billing.md#credit-and-payment-method).
* **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](https://docs.ankra.ai/guides/storage-on-your-own-cluster.md).
* **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](https://docs.ankra.ai/reference/importcluster.md).

```yaml theme={null}
apiVersion: v1
kind: ImportCluster
metadata:
  name: staging
  environment: staging
spec:
  stacks:
    - name: logging
      manifests:
        - name: logging-namespace
          from_file: manifests/logging-namespace.yaml
      addons:
        - name: fluent-bit
          chart_name: fluent-bit
          chart_version: 0.49.1
          registry_name: fluent
          registry_url: https://fluent.github.io/helm-charts
          namespace: logging
          parents:
            - kind: manifest
              name: logging-namespace
          configuration:
            from_file: values/fluent-bit.yaml
```

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.

```bash theme={null}
set -e
for file in clusters/*.yaml; do
  ankra cluster validate -f "$file" --strict-secrets
done
```

`--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:

```bash theme={null}
ankra cluster apply -f clusters/staging.yaml --wait
```

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.

> [!WARNING]
>
> 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:

```bash theme={null}
set -e
for file in clusters/*.yaml; do
  ankra cluster apply -f "$file" --wait
done
```

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](https://docs.ankra.ai/guides/ankra-pipelines.md).

**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[]`](https://docs.ankra.ai/reference/importcluster#spec-stacks-manifests) before you rename one that owns a namespace or volumes.

> [!WARNING]
>
> `--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](#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

* [Bring an existing cluster under Ankra](https://docs.ankra.ai/guides/adopt-an-existing-cluster.md) for storage, GitOps, kubectl access and backups on each cluster.
* [ImportCluster YAML Schema](https://docs.ankra.ai/reference/importcluster.md) for every field.
* [Backups and Restore Points](https://docs.ankra.ai/guides/backups.md) to protect the stateful Stacks your files declare.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.