ImportCluster YAML Schema

The ImportCluster manifest is the declarative entry point for onboarding a cluster into Ankra and describing its stacks. Apply it with the CLI:

ankra cluster apply -f cluster.yaml --cluster my-cluster

--cluster targets the cluster you name, by name or id; without it the target is the manifest’s metadata.name. cluster apply honours --cluster from CLI v0.16.0 - earlier versions ignore it and use metadata.name. The same schema is what Ankra reads from a connected GitOps repository.

Full Example

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:
            - kind: manifest
              name: 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:
            - kind: manifest
              name: 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`	no	`github` (the default) or `bitbucket_cloud`. The legacy spelling `bitbucket` is read as `bitbucket_cloud`. Any other value, `bitbucket_data_center` and `bitbucket_dc` included, is refused with a `422` naming the accepted values; matching is case-sensitive, so `GitHub` is refused too
`credential_name`	yes	Name of a Git credential registered in Ankra
`repository`	yes, for GitHub	`owner/name` form, e.g. `my-org/my-gitops-repo`. For Bitbucket Cloud, `workspace/repo-slug`
`workspace`, `repo_slug`	no	Bitbucket Cloud only: the workspace and the repository slug, in place of `repository`
`branch`	yes	Branch Ankra reads from and pushes to. The cluster’s GitOps settings list the repository’s branches to pick from, for GitHub and Bitbucket Cloud alike

Applying a changed git_repository block repoints the cluster. Ankra first writes the cluster’s current state - every stack, add-on and manifest it manages, with secrets sealed under your organisation’s key - to the new repository and branch as a commit, overwriting the files it manages there, and only then syncs from it. The new source does not need to be seeded by hand: the switch itself brings it to parity. 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 - but the branch must already exist; Ankra does not create branches. A repoint is refused until you acknowledge it: ankra cluster apply --allow-repoint, plus --allow-repoint-destroying-data when the cluster holds PersistentVolumeClaims. The refusal lists what the cluster runs today; it is not a diff against the target.

The switch is atomic. If the first write to the new source fails - the branch does not exist, the branch is protected against direct pushes, the credential’s GitHub App installation cannot reach the repository - nothing changes: the cluster keeps syncing from its current source and the error names the cause. A missing branch is reported together with the branches the repository does have.From the switch on, the new source is authoritative: anything that later leaves it is pruned from the cluster, PersistentVolumeClaims included. Keep the repository’s history if you may need to roll a change back.

Observability sources in Git

spec.prometheus_metrics and spec.log_source connect the cluster’s metrics and log data sources. Both are read back from the cluster document on every sync, so authoring or editing either block in Git connects the source and updates it - the same result as filling in the platform’s metrics or log source settings. Three rules apply to both members:

Credentials are never in Git. username, password, token and auth_scheme inside a source block are refused by name, because ignoring them would leave a live secret sitting in your repository while you believe it is in effect. Create the credential in the platform and reference it by credential_name.
Unknown top-level fields are refused, not ignored, and the error names the offending key and the accepted set. A mistyped field fails the sync rather than silently doing nothing.
Removing the block does not disconnect the source. Git can create and update a source; only the platform can disconnect one.

Deleting prometheus_metrics or log_source from the file is not a disconnect. The source survives the sync, and the next time Ankra regenerates the cluster document the block comes back. To disconnect, remove the source in the cluster’s Settings → Integrations; the platform then drops the block from Git on its own.This asymmetry is deliberate: reading “disconnect” out of an absent key is what deleted hand-written blocks before these members round-tripped, so a destructive change stays a platform action.

`spec.prometheus_metrics`

The cluster’s metrics data source. See Prometheus for endpoint examples per product.

Field	Required	Description
`endpoint`	yes	Query endpoint the Ankra agent reaches from inside the cluster. `http://` or `https://`, or a scheme-less `host:port`. Any other scheme is refused, as is an endpoint containing whitespace or control characters
`credential_name`	no	Name of a metrics credential already registered in Ankra. Omitting it does not turn authentication off: a cluster that already has a saved metrics credential keeps sending it with every query (the Metrics panel under Settings → Integrations names it), and only a cluster with no saved metrics credential queries unauthenticated - ordinary for in-cluster Prometheus. A name that resolves to no credential on the cluster fails the sync
`flavor`	no	Which Prometheus-compatible product is behind the endpoint: `self_hosted`, `grafana_cloud`, or `victoria_metrics`. Affects the labels and placeholders the portal shows, not how the endpoint is queried
`verify_ssl`	no	Verify the endpoint’s TLS certificate. Omitted means not verified, which is the historical behaviour for clusters that never set it

spec:
  prometheus_metrics:
    endpoint: http://prometheus-operated.monitoring.svc.cluster.local:9090
    flavor: self_hosted

`spec.log_source`

The cluster’s log data source. See Log Sources for provider endpoints and field-mapping defaults.

Field	Required	Description
`provider`	yes	`loki`, `elasticsearch`, or `opensearch`. Any other value is refused - the provider decides how the agent queries the store
`endpoint`	yes	Query endpoint the Ankra agent reaches from inside the cluster. Same rules as `prometheus_metrics.endpoint`
`credential_name`	no	Name of a log credential already registered in Ankra. Omit for an unauthenticated endpoint. A name that resolves to no credential on the cluster fails the sync
`tenant_id`	no	Loki tenant sent as `X-Scope-OrgID`, for multi-tenant Loki and Grafana Cloud
`index_pattern`	no	Elasticsearch/OpenSearch index pattern to search (default `*`)
`field_mappings`	no	Map of `timestamp`, `message`, `namespace`, `pod`, `container` to the paths your index actually uses. Keys outside that set are ignored rather than refused, so a mapping the platform wrote stays valid
`verify_ssl`	no	Verify the endpoint’s TLS certificate. Omitted means not verified

spec:
  log_source:
    provider: loki
    endpoint: http://loki-gateway.monitoring.svc:80
    credential_name: loki-read
    tenant_id: my-tenant

`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

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
`variables`	no	Map of stack-scoped variables, referenced as `${{ ankra.NAME }}` - highest precedence in the variable hierarchy
`manifests`	no	List of manifest entries or `- include: <path>` directives
`addons`	no	List of add-on entries or `- include: <path>` directives
`applications`	no	List of application entries
`backup`	no	The stack’s backup policy

`spec.stacks[].backup`

Protecting a stack is one block. Ankra takes scheduled restore points of the stack into the backup vault you name, on the schedule the block gives, through the same capture a manual restore point uses. For each CloudNativePG cluster it also writes the barman-cloud archiver into the cluster’s member and keeps the object store the archiver writes into in a stack member of its own, ankra-backup-policy-<stack>; see Protect a stack for what that does to the cluster. ankra cluster stacks protect <stack> writes this same block without editing the file; ankra cluster stacks unprotect <stack> sets enabled: false. See Protect a stack.

Field	Required	Description
`enabled`	no	`true` protects the stack; `false` removes protection. Default `false`
`vault`	when enabled	Name or id of the backup vault restore points are written to
`schedule`	no	`hourly`, `daily`, `weekly`, or a five-field cron expression. Default `daily`
`retention.hourly` / `.daily` / `.weekly` / `.monthly` / `.yearly`	no	How many restore points of each calendar period to keep. `0` (the default) disables that tier
`retention.minimum_count`	no	Keep at least this many restore points however the tiers fall out
`retention.minimum_age`	no	A Go duration (`24h`, `720h`). Nothing younger than this is expired
`selection.databases`	no	Whether the stack’s database clusters are captured. Default `true`
`selection.persistent_volume_claims`	no	Names of the volume data assets to capture. Default empty
`selection.confirm_exclude_databases`	when excluding	Required acknowledgement when `selection.databases` is `false`

stacks:
  - name: platform
    backup:
      enabled: true
      vault: offsite
      schedule: daily
      retention:
        daily: 7
        weekly: 4
        monthly: 6
        minimum_count: 3
        minimum_age: 24h
      selection:
        databases: true
        persistent_volume_claims:
          - grafana/grafana-storage
    addons: [...]

Protecting a stack does not sweep every volume in it. Databases are captured by default, because a restore point without the database contents is the one nobody forgives. Volumes are captured only when you name them in selection.persistent_volume_claims, because a stack’s namespaces routinely hold caches, scratch space and metrics storage that nobody wants copied to object storage every night. Use the stack’s data inventory - ankra cluster stacks data list <stack> - to see the asset names.

Excluding databases needs an acknowledgement. Setting selection.databases: false requires selection.confirm_exclude_databases: true in the same block, and the stack then carries a standing warning: its restore points bring back volumes and configuration, but no database contents. The acknowledgement covers the write that carried it - a later edit that keeps databases excluded has to say so again.

An omitted block never removes protection. A file that does not mention backup leaves the stored policy exactly as it was. That is deliberate: ankra cluster apply replaces a stack with what the file says, and an older CLI or a hand-written file that simply did not know about the block would otherwise unprotect the stack in silence. Removing protection is backup: {enabled: false} - something a person typed. When an apply does narrow protection, the result carries a warning naming what is no longer covered. The schedule itself is never stored as a stack member: it is read from this block every time the stack is due, so no apply, clone or profile capture can leave a stack with a schedule that no longer matches its policy. The two things protect does write into the stack for a CloudNativePG cluster - the archiver on the Cluster and the ankra-backup-policy-<stack> member holding its object store - are Ankra’s: a clone and a profile capture leave both out and say so. An apply that replaces the stack from a file without them heals in two ways, depending on what the file dropped. If only the object store member went, the next restore point - scheduled or manual - puts it back, because that restarts nothing. If the archiver itself went, scheduled backups are skipped with archiver_not_wired until you protect the stack again or take a restore point by hand; either puts the archiver back and restarts the instances once.

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.

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 still control resource-level order.

Include paths

Instead of inline entries, reference files or folders in the repository. Ankra loads every YAML file found:

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. The name is the manifest’s identity: renaming it is a delete of the old manifest plus a create of the new one, see the warning below
`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 - deploy only after these succeed
`encrypted_paths`	no	Key names Ankra seals with SOPS when it writes the manifest to Git. An entry names a key, not a location: every key of that name is sealed at every depth - see What an Entry Actually Matches. On an update, omit it to keep the stored declaration; an explicit `[]` sent over the API clears it, while the CLI drops an empty list - see An Empty or Absent Declaration
`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. 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

Renaming a manifest deletes its resources. Ankra identifies a manifest by its name, not by its content. When a stack is applied (with ankra cluster apply, a GitOps sync, or an edit in the portal) and a manifest name is no longer present, Ankra removes that manifest and runs the equivalent of kubectl delete on every object in its stored YAML. A manifest that appears under a new name is applied as a new manifest, and nothing orders that apply against the delete of the old one.For a manifest that holds a Namespace, this deletes the namespace and every PersistentVolumeClaim in it. For a manifest that holds PVCs, the delete removes the PVCs the new manifest has just applied. With a StorageClass whose reclaimPolicy is Delete (the default for most CSI drivers, including AWS EBS gp3), the underlying volumes are destroyed as well.Keep the names of manifests that own namespaces or stateful resources fixed. If you must rename one, move its data first, or make sure the PersistentVolumes behind it use reclaimPolicy: Retain. See Protect Persistent Data Before Changing a Stack.

`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
`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): 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; see SOPS. Same empty-versus-absent rule as a manifest’s `encrypted_paths`
`parents`	no	Dependency edges
`settings`	no	Sync behaviour for the add-on (automated sync, prune, self-heal, retry) - 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. 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 defaults to fully automated. See Add-on Settings for semantics.

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 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
`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. Every parent is a kind + name pair - write both keys:

parents:
  - kind: manifest
    name: namespace-fluent-bit
  - kind: addon
    name: cert-manager

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. Parents reference the other resource by name. Because a rename is a delete plus a create (see the manifests warning), renaming a parent also means updating every parents entry that points at it in the same change.

The shorthand - manifest: <name> does not work. It parses to an empty parent and the dependency edge is silently dropped - the resource deploys unordered, and both local and server-side validation still pass, because parent names are never resolved. Verify what was actually stored with ankra cluster stacks list <stack> -o json, which echoes each resource’s real parents.

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 <id> to additionally validate against that cluster’s live resources, exactly as an apply to it would. validate also warns when a declared encrypted_paths entry seals more keys than the one it names (category encrypted_paths_over_match, see What an Entry Actually Matches). The warning is computed from the entries you declare, so a resource with an empty declaration never produces one, and ankra cluster apply does not report it - run validate first when a pipeline drives the API.

Get Started

Use Cases

Concepts

Create and Run Clusters

Ship Your App

Stacks and Add-ons

Observe and Troubleshoot

Ankra AI

Connect Tools

Source Control

Security and Access

Cost and Backups

Organisation and Account

Reference

ImportCluster YAML Schema

Full Example

Top Level

`spec.git_repository`

Observability sources in Git

`spec.prometheus_metrics`

`spec.log_source`

`spec.helm_registries[]`

`spec.stacks[]`

`spec.stacks[].backup`

Deploy waves

Include paths

`spec.stacks[].manifests[]`

`spec.stacks[].addons[]`

`settings` defaults

`spec.stacks[].applications[]`

Parents

Validation

​Full Example

​Top Level

​spec.git_repository

​Observability sources in Git

​spec.prometheus_metrics

​spec.log_source

​spec.helm_registries[]

​spec.stacks[]

​spec.stacks[].backup

​Deploy waves

​Include paths

​spec.stacks[].manifests[]

​spec.stacks[].addons[]

​settings defaults

​spec.stacks[].applications[]

​Parents

​Validation

Full Example

Top Level

`spec.git_repository`

Observability sources in Git

`spec.prometheus_metrics`

`spec.log_source`

`spec.helm_registries[]`

`spec.stacks[]`

`spec.stacks[].backup`

Deploy waves

Include paths

`spec.stacks[].manifests[]`

`spec.stacks[].addons[]`

`settings` defaults

`spec.stacks[].applications[]`

Parents

Validation