> ## 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.
# ImportCluster YAML Schema
> Every field of the ImportCluster manifest - metadata, git_repository, stacks, manifests, add-ons, applications, parents, and SOPS encrypted_paths.
The `ImportCluster` manifest is the declarative entry point for onboarding a cluster into Ankra and describing its stacks. Apply it with the CLI:
```bash theme={null}
ankra cluster apply -f cluster.yaml --cluster my-cluster
```
The same schema is what Ankra reads from a connected [GitOps repository](/concepts/gitops).
## Full Example
```yaml theme={null}
apiVersion: v1
kind: ImportCluster
metadata:
name: my-cluster
description: Importing my Kubernetes cluster
spec:
git_repository:
provider: github
credential_name: my-git-credential
repository: my-org/my-gitops-repo
branch: main
stacks:
- name: logging
description: Stack for logging
manifests:
- name: namespace-fluent-bit
parents: []
from_file: "manifests/fluent-bit-namespace.yaml"
- name: configmap-fluent-bit
parents:
- manifest: namespace-fluent-bit
from_file: "manifests/fluent-bit-configmap.yaml"
agents_md_from_file: "manifests/fluent-bit-configmap.AGENTS.md"
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: fluent-bit
parents:
- manifest: configmap-fluent-bit
agents_md_from_file: "addons/fluent-bit/AGENTS.md"
configuration:
values: |-
service:
enabled: true
```
## Top Level
| Field | Required | Description |
| ---------------------- | -------- | ------------------------------------------------ |
| `apiVersion` | yes | Always `v1` |
| `kind` | yes | Always `ImportCluster` |
| `metadata.name` | yes | Cluster name - letters, digits, and hyphens only |
| `metadata.description` | no | Free-text description shown in the platform |
| `spec` | yes | The cluster specification |
## `spec.git_repository`
Connect a Git repository so stacks are stored and synced from Git. Omit the block entirely for a non-GitOps import.
| Field | Required | Description |
| ----------------- | -------- | ------------------------------------------------------- |
| `provider` | yes | `github`, `bitbucket_cloud`, or `bitbucket_data_center` |
| `credential_name` | yes | Name of a Git credential registered in Ankra |
| `repository` | yes | `owner/name` form, e.g. `my-org/my-gitops-repo` |
| `branch` | yes | Branch Ankra reads from and pushes to |
Applying a changed `git_repository` block **repoints the cluster**: Ankra reads from the new repository and branch from the next sync on. Any branch works - a cluster is not tied to its repository's default branch, so one repository with a branch per environment is a supported layout.
Repointing is destructive. Ankra removes resources that are no longer defined in the connected source, so if the new repository or branch does not define a stack the cluster is currently running, that stack is pruned - including any PersistentVolumeClaims it owns.
Before repointing, diff the two sources over the cluster's directory and confirm the new one defines everything you expect to keep:
```bash theme={null}
git diff old-remote/main new-remote/develop -- clusters//
```
## `spec.helm_registries[]`
Declare the Helm registries the file's add-ons depend on, so the repository is self-contained: applying the file connects any registry that is not already present before add-ons deploy. A declaration matching an existing registry (same name, same URL - org-scoped or global) is an idempotent no-op; a declaration whose name is taken by a registry with a different URL fails the apply before anything is written. Credentials are referenced by name and must already exist, so secrets stay out of Git.
| Field | Required | Description |
| ----------------- | -------- | ---------------------------------------------------------------------------------------- |
| `name` | yes | Registry name, referenced by add-ons via `registry_name` |
| `url` | yes | Registry URL - `https://...` for HTTP chart repositories, `oci://...` for OCI registries |
| `credential_name` | no | Name of a Helm registry credential registered in Ankra, for private registries |
| `exclude_charts` | no | Chart names to skip during indexing |
```yaml theme={null}
spec:
helm_registries:
- name: ory
url: https://k8s.ory.com/helm/charts
- name: private-hub
url: oci://artifact.example.com/charts
credential_name: example-harbor-pull
```
## `spec.stacks[]`
Each stack groups related manifests, add-ons, and applications.
| Field | Required | Description |
| ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | yes | Stack name, unique within the cluster |
| `description` | no | Free-text description |
| `description_from_file` | no | Read the description from a file path in the repo |
| `deploy_wave` | no | Integer `>= 0` ordering stacks against each other - see [Deploy waves](#deploy-waves) |
| `variables` | no | Map of stack-scoped variables, referenced as `${{ ankra.NAME }}` - highest precedence in the [variable hierarchy](/concepts/variables) |
| `manifests` | no | List of [manifest entries](#spec-stacks-manifests) or `- include: ` directives |
| `addons` | no | List of [add-on entries](#spec-stacks-addons) or `- include: ` directives |
| `applications` | no | List of [application entries](#spec-stacks-applications) |
### Deploy waves
`deploy_wave` sequences whole stacks: a stack in wave N starts deploying only after every stack in a lower wave finished successfully, and teardown unwinds in reverse wave order. Stacks in the same wave deploy in parallel, and stacks without a `deploy_wave` stay independent of the ordering entirely - existing clusters keep their current behaviour.
```yaml theme={null}
stacks:
- name: infrastructure # cert-manager, ingress, storage
deploy_wave: 1
addons: [...]
- name: platform # databases, message queues
deploy_wave: 2
addons: [...]
- name: applications # your workloads
deploy_wave: 3
addons: [...]
- name: monitoring # independent: deploys any time
addons: [...]
```
Wave numbers do not need to be contiguous - `1, 5, 20` works and leaves room to slot stacks in later. If a stack in wave N fails, later waves stay blocked until it is fixed or removed. Within a stack, [parents](#parents) still control resource-level order.
### Include paths
Instead of inline entries, reference files or folders in the repository. Ankra loads every YAML file found:
```yaml theme={null}
stacks:
- name: platform-stack
manifests:
- include: manifests/
addons:
- include: addons/
- include: addons/extra/ingress.yaml
```
## `spec.stacks[].manifests[]`
Raw Kubernetes YAML resources.
| Field | Required | Description |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | yes | Manifest name, unique within the cluster |
| `from_file` | one of | Repo-relative path to the YAML file (forward slashes, resolved from the manifest's location) |
| `manifest` / `manifest_base64` | one of | Inline content (the CLI accepts plain YAML under `manifest:` and encodes it) |
| `parents` | no | [Dependency edges](#parents) - deploy only after these succeed |
| `encrypted_paths` | no | YAML paths within the manifest that are SOPS-encrypted; see [SOPS](/guides/sops) |
| `force` | no | Replace the live object on conflict instead of failing (default `false`) |
| `auto_remediate` | no | Re-apply automatically when drift is detected (default `false`) |
| `group` | no | Organizational grouping label within the stack (max 63 characters). Purely visual - grouping resources never changes deployment order and never triggers a redeploy |
| `agents_md` | no | Inline markdown of operational learnings for this manifest - see [AGENTS.md](/platform/agents-md). Documentation-only - never triggers a redeploy |
| `agents_md_from_file` | no | Repo-relative path to an AGENTS.md file to read the content from instead of inlining it |
| `dependencies_override` | no | Advanced: override computed dependency ordering |
## `spec.stacks[].addons[]`
Helm releases.
| Field | Required | Description |
| ---------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | yes | Add-on name, unique within the cluster |
| `chart_name` | yes | Chart name in the registry |
| `chart_version` | yes | Exact chart version - pin it, especially in production |
| `registry_name` | yes | Name of the Helm registry connected in Ankra - see [Registries](/guides/registries) |
| `registry_url` | yes | URL of that registry, e.g. `https://fluent.github.io/helm-charts` |
| `namespace` | yes | Target namespace for the release. Must be a valid Kubernetes namespace name ([RFC 1123 DNS label](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names)): 1-63 characters, lowercase letters, digits and `-`, starting and ending with a letter or digit. Short names like `ory` are fine. `ankra cluster validate` enforces the same rules as apply |
| `registry_credential_name` | no | Credential for private registries |
| `configuration.values` / `values_base64` | no | Helm values, inline |
| `configuration.from_file` | no | Repo-relative path to a values file |
| `configuration.encrypted_paths` | no | Values paths that are SOPS-encrypted |
| `parents` | no | [Dependency edges](#parents) |
| `settings` | no | ArgoCD-backed sync behaviour - see below |
| `namespace_migration_strategy` | no | How to handle a namespace change on update |
| `job_configuration` | no | Per-add-on job timeouts (`read_job_timeout`, `update_job_timeout`, `delete_job_timeout`) |
| `group` | no | Organizational grouping label within the stack (max 63 characters). Purely visual - never triggers a redeploy |
| `agents_md` | no | Inline markdown of operational learnings for this add-on - see [AGENTS.md](/platform/agents-md). Documentation-only - never triggers a redeploy |
| `agents_md_from_file` | no | Repo-relative path to an AGENTS.md file to read the content from instead of inlining it |
### `settings` defaults
Sync behaviour maps to ArgoCD and defaults to fully automated. See [Add-on Settings](/concepts/addon-settings) for semantics.
```yaml theme={null}
settings:
sync_policy:
automated: true
auto_prune: true
self_heal: true
sync_options:
- CreateNamespace=true
- ServerSideApply=true
retry_policy:
limit: 5
backoff_duration: 5s
backoff_factor: 2
backoff_max: 3m
```
## `spec.stacks[].applications[]`
Deployments of [Applications](/concepts/applications) created in Ankra.
| Field | Required | Description |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------- |
| `name` | yes | Application resource name |
| `platform_application_id` | no | The Ankra application to deploy |
| `platform_application_version` | no | Pinned application version |
| `namespace` | no | Target namespace |
| `parameters` | no | Map of application parameters |
| `parents` | no | [Dependency edges](#parents) |
| `group` | no | Organizational grouping label within the stack (max 63 characters). Purely visual - never triggers a redeploy |
## Parents
`parents` are the dependency edges that control deployment order: a resource deploys only after all of its parents succeed. Two equivalent syntaxes are accepted:
```yaml theme={null}
# Shorthand
parents:
- manifest: namespace-fluent-bit
- addon: cert-manager
# Explicit
parents:
- name: namespace-fluent-bit
kind: manifest
```
`kind` must be `manifest` or `addon`, and the parent must be defined somewhere in the same file. Namespace manifests must be parents of everything deployed into that namespace.
## Validation
`ankra cluster apply` validates the file before sending anything: unknown fields, missing parents, and invalid parent kinds are rejected with the offending path. Use `--dry-run` to validate without applying.
`ankra cluster validate -f cluster.yaml` is the server-side pre-flight gate, built for CI: it runs every rule apply enforces without touching the cluster. That covers structure (duplicate names, missing parents, dependency cycles), chart resolution (registry connected, chart exists, pinned version exists), plaintext-secret detection, and the per-resource field rules - add-on namespaces (Kubernetes DNS label: 1-63 characters, lowercase letters, digits and `-`, starting and ending with a letter or digit), group names, and empty manifest bodies. Pass `--cluster ` to additionally validate against that cluster's live resources, exactly as an apply to it would.