Repository Structure
There are two ways a cluster’s files end up in a repository, and they can look different. The layout Ankra writes. When you connect a repository, or change a cluster in the portal, CLI, API or through Ankra’s AI, Ankra writes the cluster to its own directory:my-cluster.yaml, is the cluster file, and it is the only file Ankra reads as a cluster definition. Every other file in the directory is content: it takes effect when an entry in the cluster file names it with from_file. You can add your own files anywhere in the directory except under argocd/, in subdirectories too:
AGENTS.md sibling files hold per-manifest and per-add-on operational learnings for your team and Ankra’s AI - see Teach Your Agents with AGENTS.md.
Cluster Definition Example
The cluster file lists every manifest and add-on byname and points at its file with from_file. For the directory above, my-cluster.yaml reads:
from_file, agents_md_from_file and description_from_file is a path relative to the cluster directory, and Ankra looks it up exactly as written among the files in that directory. There is no folder or wildcard form, a path that leaves the directory never matches, and Ankra never follows a symlink. When a manifest, an add-on’s values, an application or a stack description names a file that is not there, the sync stops with an error ending which is not in the repository snapshot and applies nothing; a missing AGENTS.md file is skipped. An entry without a name stops the sync too: every manifest, add-on and application entry needs one.
One kind of file needs no entry. A file at stacks/<stack>/manifests/<name>.yaml (or .yml) that no entry already names, for a stack the cluster file declares, is added to that stack as a manifest called <name>, unless a stack already lists that name. If two declared stacks hold a file with the same unlisted name, the sync stops until you list it under the stack you mean.
ankra cluster apply -f reads the same keys on your machine. It resolves each path against the directory the applied file is in and refuses a path that is absolute or contains .., so running it on the cluster file in its cluster directory resolves the same from_file paths a sync does; it does not add unlisted manifest files. Files in the cluster directory lists every key that names a file.
Single-File Cluster Definition
A cluster file you apply withankra cluster apply -f can instead carry everything inline, with manifest and values content embedded as base64. This form is for the CLI only: a sync from Git refuses a cluster file whose manifests carry manifest_base64, and reads a manifest’s content only from its file:
parents to control deployment order: a resource deploys only after its parents succeed. When Ankra writes a cluster like this to Git, it moves each manifest’s and add-on’s content into a file in the cluster directory and names it with from_file, as in the cluster definition example.
Every field of this file - stacks, manifests, add-ons, applications, parents, and encrypted paths - is documented in the ImportCluster YAML Schema.
Data Sources in the Cluster Document
The cluster’s metrics and log data sources live in the same file, asspec.prometheus_metrics and spec.log_source. Both are read back on every sync, so writing either block in Git connects the source and updates it - you do not have to configure it in the platform first:
username, password, token or auth_scheme inside a source block is refused, and the credential is referenced by credential_name instead. Deleting a block does not disconnect the source - Git can create and update one, only the platform can disconnect it. See spec.prometheus_metrics and spec.log_source.
How Ankra Syncs Your Cluster
- You update or add YAML files in your Git repository
- Ankra detects the change and automatically syncs your cluster
- Ankra reads the cluster file and the files it names with
from_file, and applies the manifests and add-ons in the order you specify
What Ankra Writes Back to Git
Sync is two-way. Changes you commit are applied to the cluster, and changes made through the portal, the CLI, the API or Ankra AI are written back to the cluster’s directory in the repository, so Git stays the record. A platform write lands as a commit authored byankra-platform[bot] (a change made in the portal, CLI or API) or by Ankra Reconciler with the subject Sync cluster state from Ankra (the reconciler exporting stored state).
The ownership manifest: .ankra-owned.json
Every cluster directory carries a file named .ankra-owned.json. Ankra rewrites it on each platform write. It is a record of what that write rendered - not an inventory of the directory, and not a claim on it:
pathslists the files the last write rendered. It bounds deletion: when a stack or add-on is removed, only files listed here are pruned. A file Ankra never rendered is never deleted, only reported.contentsmaps each rendered file to a digest of the bytes Ankra itself last wrote there. It bounds overwriting: before writing a file, Ankra compares what is in Git with that digest. If they differ, the file was edited since, and Ankra keeps the Git version instead of replacing it.
Hand-maintaining a file
To keep a value Ankra would otherwise render - an image tag pinned above a chart’sappVersion for a CVE fix, an updateStrategy, topologySpreadConstraints - edit the file in Git and merge it. Ankra syncs the change into the cluster, and from then on the file’s bytes in Git no longer match the digest Ankra recorded, so no platform write replaces them. This holds for every write path: portal, CLI, API, Ankra AI and the reconciler’s own export.
Three limits apply today:
- SOPS-encrypted files are not covered. Their committed bytes are ciphertext that cannot be reproduced from the render, so Ankra keys them on the embedded content fingerprint instead, and re-encrypts the file whenever its stored values change. A hand edit to an encrypted file sealed under the cluster’s
.sops.yamlis imported like any other Git change and then re-sealed by Ankra’s next write - the values survive, the ciphertext does not, so expect one re-seal commit after rotating a sealed Secret by hand (see Rotating by API and SOPS). .sops.yamlin the cluster directory has its own rule. Ankra rewrites the creation rules it generates there on every export, but it no longer replaces the file: rules you add by hand are kept, and kept above Ankra’s own. See Merging the SOPS configuration file below.- The portal and the MCP tools cannot decide a preserved file. While a file is preserved, a change made to it in Ankra does not reach Git, and the cluster reads Diverged for as long as the two versions differ. The portal shows the Diverged status but neither lists the files nor shows both versions;
ankra cluster gitops statuslists them, andankra cluster gitops preserved(CLI v0.59.0 or later) and the API show and decide them. No MCP tool decides one. See Diverged files below.
Diverged files
A file you edited in Git stays yours: no later platform write replaces it. When a later change in Ankra would change that file - an edit through the portal, the CLI, the API, Ankra AI or an MCP client, or a change Ankra makes to the cluster itself - Ankra keeps your bytes, records the file as preserved with both versions, and the cluster’s GitOps status readsdiverged instead of synced, with the files in preserved_paths. The cluster’s Settings → GitOps page shows the status Diverged.
- Nothing is paused. Unlike a conflict, a preserved file does not hold the sync. Commits to it and to every other file keep being applied, including a new stack or manifest you register in a preserved cluster file. Only Ankra’s own change to that file waits.
- Only a difference in substance counts. YAML and JSON are compared as decoded documents, so comments, key order and quoting alone never make a cluster diverged. Your file is still kept byte for byte.
- It clears when the two versions agree again - you make the same change in Git, or Ankra’s side changes back - or when a person decides it. It does not clear by waiting.
list prints each preserved file with when it was detected, its decision, whether its content is withheld and why, and how many differences the platform found. show <path> prints those differences key by key, read from Git’s version to Ankra’s: added (only Ankra’s version has it), removed (only Git’s has it), changed (both have it, with different values) or reordered (both list the same members in another order). It shows Git’s and Ankra’s value where the platform shows them and (masked) where it does not: seeing values needs kubernetes.secrets_reveal on the cluster, and some files show no values to anyone. The platform lists at most 50 differences per file and always gives the total. Name a file by its full repository path, as list prints it.
resolve <path> records the decision, and the next sync runs it; resolve triggers that sync. --keep is required, because the decision names the version the next sync writes:
Before it asks,
resolve prints the platform’s key-by-key difference: each stack or add-on only one version declares on one line, and each value that changes. When keeping Git’s version would drop encrypted_paths entries that Ankra’s version declares, it warns that, if Git holds those values SOPS-encrypted, Ankra would stop decrypting them and deploy the ciphertext as the value. --yes skips the question, and without a terminal to ask on (a script, CI) it is required. resolve reads both digests from the listing itself, so you never type one and the decision covers exactly the two versions it showed you. Deciding needs clusters.write on the cluster. -o json prints the platform’s answer.
The same steps through the API take two calls with an API token (a token scoped to MCP is refused), and the decision needs clusters.write on the cluster:
path, Git’s version as head_content (read at head_commit_sha), Ankra’s version as render_content, the digest of each as head_content_hash and render_content_hash, when the difference was first seen as detected_at, and any resolution_choice already made. A file that may hold a secret is listed with content_redacted and no content; its digests are still exact.
Each entry also carries structural_diff, even when its content is withheld: the key path of every key or list member where the two versions differ, each marked added, removed, changed or reordered from Git’s version to Ankra’s. A value is shown only where Ankra’s checks find nothing sensitive in it, and only to a caller holding kubernetes.secrets_reveal on the cluster; where a side holds a value that is not shown, the change reads value_masked: true, and a key name that may itself be a secret reads <masked>.
resolution takes the values in the table above.
A decision is pinned to the two digests it names. If either version has changed by the time it arrives, it is refused with 409: resolve says so and asks you to run the same command again, which reads the file again, and an API caller lists again. If one changes before the sync runs it, the decision is cleared. A different decision already recorded is refused too; withdraw it first. A git import Ankra refuses - one that would lower a chart version, for example - records why in import_refused_reason and clears the decision, so you decide again: list shows the file as undecided (last keep-Git refused) and show prints the reason. A git import never removes a stack: a stack Ankra declares and your file leaves out stays, and the file stays preserved, until you declare the stack in the file or remove it through the platform.
Merging the SOPS configuration file
The.sops.yaml in a cluster directory has two authors, so it is not covered by the digest boundary above: it is merged on every platform write instead of replaced, and the file it writes opens with a header saying so.
- Ankra owns only the rules it generates: a rule carrying a
path_regexAnkra generates, anagekey, and at most anencrypted_regex- and nothing else. Ankra rewrites those on every sync and lists them last in the file. While the cluster declaresencrypted_paths, each generated rule carries anencrypted_regexbuilt from the union of every declaration across the cluster’s stacks, rebuilt on every sync as the declarations change, so asops -ethat applies the rule seals only declared secret keys and leaves every other key readable. It is one union per cluster, so it is broader per file than what Ankra itself seals per resource: a key declared secret for any resource in the cluster is sealed in every matching file. - Every other rule is yours. It is preserved verbatim and kept above Ankra’s own. SOPS applies the first matching creation rule, so a rule of yours takes precedence over Ankra’s - including a deliberately keyless first rule, which is the supported way to keep a path out of encryption and make an external
sops -eon it fail loudly rather than seal a file that must stay plaintext. Write itspath_regexrelative to the cluster directory, not the repository root:sopsmatches a rule against the file’s path relative to the directory holding the.sops.yamlit is using, so for the cluster’s file the path being tested isstacks/<stack>/add-ons/<add-on>/values.yaml. A rule written from the repository root never matches, and a refusal caused by nothing matching is an accident, not protection - see Checking that a keyless rule applies. - To override one of Ankra’s rules, write a rule that is not shaped like Ankra’s: keyless, using
key_groups, carrying a field other thanpath_regex,ageandencrypted_regex, or on a differentpath_regex. A rule that is apath_regexAnkra generates plus anagekey, with or without anencrypted_regex, cannot be told apart from Ankra’s own output and is replaced whatever itsageorencrypted_regexvalues are - that is what lets a key rotation or a changed declaration reach the file, and it happens silently. To keep your own recipients or your ownencrypted_regexon a path Ankra covers, name the recipients withkey_groups. The warning below spells it out. - Other top-level keys are yours too.
stores,kms,shamir_thresholdand anything else in the file are carried through untouched. - Ankra does not read these rules. Its own encryption is driven per resource by that resource’s
encrypted_pathsdeclaration, compiled to a SOPSencrypted_regexwhen the resource is sealed (see SOPS). The file exists for external tooling that runssopsagainst the repository.
.sops.yaml Ankra cannot parse is left exactly as it is, rather than rewritten.
Checking that a keyless rule applies
sops looks for .sops.yaml by walking up from the current directory, not from the file it is given, and matches each path_regex against the file’s path relative to the directory holding that .sops.yaml. Test a rule from the repository root with an explicit --config, writing to stdout (never -i):
Pair the check with a positive control in the same run: a neighbouring file that only a rule with recipients covers must encrypt, or the refusal proves nothing about your rule. Ankra’s generated rules are written relative to the cluster directory (
.*values\.yaml$ and .*manifests/.*\.yaml$), so on a cluster synced since that change they match and can serve as the control: a values file only they cover must encrypt. A .sops.yaml still carrying the older repo-rooted spellings (<cluster-directory>/.*values\.yaml$) predates the change - those rules match nothing, Ankra’s next write to the cluster replaces them, and until then a control needs a keyed rule of your own, written relative to the cluster directory like the keyless one.
When Git and the Platform Both Change
Because sync is two-way, the same resource can change on both sides between two syncs: someone edits a stack in the portal while a commit to the same stack lands in Git. Ankra does not guess which side you meant. On every sync Ankra compares three things: the head of the branch, the state stored in the platform, and the baseline both sides last agreed on. That comparison has four outcomes:
A conflict pins the cluster’s sync. Nothing further is applied from Git and nothing further is pushed to it until every conflicting resource has a decision. For each one you choose Git (the committed version wins and the platform change is dropped) or Cluster (the platform version wins and is committed over the Git version). In the portal, conflicts are listed under Merge conflicts on the cluster’s Settings → GitOps page, with when each was found and the version kept. Each row’s menu offers Compare the two versions…, Keep the Git version… and Keep the cluster version…, and Resolve all… decides every open conflict at once; a Secret’s contents are not shown in the comparison. You can also resolve them with the
list_gitops_conflicts, get_gitops_conflict_diff and resolve_gitops_conflict MCP tools. Sync resumes on its own once the last conflict is decided.
From a terminal, list the open conflicts and record which side each one keeps:
list prints each conflict’s resource key, and resolve takes that key, or --all for every open conflict. --keep is required, because either side discards the other: git is the same choice as Git above and cluster the same as Cluster. resolve shows what it is about to decide and asks first; --yes skips the question, and you need it where there is no terminal to ask on, such as CI.
A script with an API token can call the same routes: GET /api/v1/org/clusters/{cluster_id}/gitops/conflicts lists the conflicts, and a POST to /api/v1/org/clusters/{cluster_id}/gitops/conflicts/resolve or to .../gitops/conflicts/resolve-resource decides all of them or one. Any member of the organisation can list conflicts; resolving one needs clusters.write on the cluster.
There is no setting that makes one side win automatically. If Git should be the authority for a cluster, make changes to that cluster only through Git: with no platform-side edits there is nothing to conflict with. If a platform write finds a commit in Git that Ankra has not imported yet, the change is saved in the platform but its push to Git is held back, and the next sync merges the two sides or raises a conflict as above.
Connecting a repository to a cluster that already has state
When you connect a repository to a cluster Ankra is already managing, Ankra first pushes the cluster’s current state to the repository as a commit namedConnect GitOps repository, then starts syncing. Connect an empty repository, or one Ankra has written to before. A repository that already holds files at the paths Ankra renders, and has no .ankra-owned.json, has no overwrite boundary yet, so that first push can replace those files.
You do not need a repository at all. With the native engine, Ankra reconciles stacks and add-ons from the state stored in the platform, and a cluster with no repository connected is fully supported. Connecting one adds Git as a second place to read and make changes; it does not change how the cluster is reconciled.
Watching Sync in the Portal
Everything about a cluster’s repository is on Infrastructure → Clusters → <your cluster> → Settings → GitOps (/next/clusters/<cluster-id>/settings/gitops). The page has a section for each part of the sync:
- Repository: the repository, branch and credential the cluster syncs with. Without one, the section reads No repository connected and offers Connect a repository; with one, Change repository points the cluster somewhere else.
- Sync: whether the cluster matches its repository. Ankra syncs by itself when the branch changes, and Sync now checks the repository right away. The section shows the Status, when the cluster Last synced, the Last commit applied, and, while one is pending, the Commit waiting to be applied and the Tries so far.
- Merge conflicts: resources changed both in Git and in Ankra since the last sync, described in When Git and the Platform Both Change.
- Sync history: every sync, newest first, with what started it, the commit and the result.
- Cluster definition: what Ankra writes to the repository for this cluster, its Stacks and the manifests, add-ons and applications in each, with Open the files in the repository for the files themselves.
Sync status
Applied Commit and Git Head
ankra cluster gitops status and GET /api/v1/clusters/{cluster_id}/gitops/status report the last sync time and commit (last_synced_at, last_commit_sha) for the last full sync only. Beside them are two pointers:
- Applied Commit (
applied_commit_sha,applied_commit_at): the commit Ankra holds the cluster in step with, and since when. - Git Head Checked (
head_checked_sha,head_checked_at): the head of the branch as Ankra last read it, and when.
Sync now
Ankra picks up a push through the repository’s webhook, and checks the repository on its own as well. Sync now checks it straight away: use it when a webhook delivery failed, or when you want a fix you just pushed applied without waiting. It needs permission to change the cluster’s GitOps settings; a role without it sees the status but no button.Sync history
Each row in Sync history says what started the sync (A push to the repository, Someone asked for a sync, Ankra’s regular check, or A change made in Ankra), the commit, and the result. Opening a row shows the steps of that sync with the result and duration of each, and names the step that failed.Handling Sync Errors
When a sync fails, Ankra provides detailed error information to help you fix issues quickly.Error Display
Failed syncs show:- Validation Errors: Issues with YAML syntax or configuration
- Field-Level Guidance: Specific fields that need attention
- Missing Fields: Required fields that weren’t provided
- Typo Detection: Suggestions for misspelled field names
Common Error Types
Validation Errors
Validation Errors
YAML syntax issues or invalid configuration values.Solution: Check the error details for the specific field and fix the YAML in your repository.
Missing Required Fields
Missing Required Fields
Required configuration fields weren’t provided.Solution: The error shows which fields are missing with examples of expected values.
Resource Conflicts
Resource Conflicts
A resource already exists or conflicts with another definition.Solution: Check for duplicate resource names or conflicting configurations.
A Section That Is Not a List
A Section That Is Not a List
spec.stacks, or a stack’s manifests, addons or applications, is present but is not a list: a lost - or an indentation slip turns a list into a mapping, and a key with nothing after it is null. Nothing is applied, because reading it as an empty list would remove everything it declared before; the error names the section, for example stack "logging": addons must be a list, got a mapping.Solution: Fix the YAML. To declare none, write an empty list, for example addons: [].Large Removals Are Held
A sync that would remove a large share of the cluster at once is held: nothing in the commit is applied, and the sync fails with an error that startsGitOps sync held, nothing was applied: this commit would remove and names what would go. A sync is held when it would:
- Remove two or more stacks that have members, when they are half or more of the cluster’s stacks with members, or more than three of them
- Remove two or more add-ons, manifests or applications from the stacks it keeps, when they are half or more of those stacks’ members, or more than five of them
- Remove every member of a kept stack that has two or more
ankra cluster stacks delete and ankra cluster manifests delete. The next sync then applies the rest of the same commit, without a new push; Sync now runs it straight away. If the removal is a mistake, such as a YAML slip or a merge conflict resolved the wrong way, restore them in the cluster file and push.
Retrying Failed Syncs
A failed sync is retried by fixing the cause in the repository and pushing the fix. The push starts a new sync; Sync now starts one without waiting, and the new attempt appears at the top of Sync history. A held large removal you meant to make needs no change in Git: remove those stacks or members through Ankra, and the next sync applies the same commit.Troubleshooting
If Ankra isn’t syncing as expected:Related
- Stacks - Learn about organizing resources into stacks
- Add-ons - Install Helm charts as add-ons
- Manifests - Deploy your own Kubernetes YAML
Still have questions? Join our Slack community and we’ll help out.