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:

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

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

git diff old-remote/main new-remote/develop -- clusters/<cluster-name>/

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

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
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	YAML paths within the manifest that are SOPS-encrypted; see 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. 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
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
parents	no	Dependency edges
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. 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 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. Two equivalent syntaxes are accepted:

# 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 <id> to additionally validate against that cluster’s live resources, exactly as an apply to it would.