How an add-on reaches the cluster
- Stack editor or Git: you choose the chart, pin its version and set its values in the Stack editor, or in a connected GitOps repository.
- Ankra platform: stores the desired state of the Stack and dispatches the deploy.
- Ankra agent: receives the deploy inside your cluster.
- Helm release: the agent runs
helm upgrade --installwith your values. The step succeeds once the release is healthy. - Kubernetes resources: the rendered manifests are applied to the cluster.
What an add-on is made of
You add an add-on to a Stack from Add → Helm add-on in the Stack editor. The Add a Helm add-on dialog searches the charts of the Helm registries your organisation has connected (Find a chart), then asks for four things:
A chart only appears once its registry is connected. Connecting a public or private Helm repository or OCI registry is described in Registries, and hosting your own charts on GHCR in Create a Registry.
Once added, the add-on is a member of the Stack. Selecting it in the editor opens its resource editor:
Every change you make lands in the Stack’s shared draft and reaches the cluster only when the draft is deployed. How drafts, review and deployment work is explained in Stacks.
Keeping secrets out of values
A password, an API key or a webhook URL does not belong in an add-on’s values as plain text. Ankra has two ways to keep it out:- Organisation secrets. Store the value once under Infrastructure → Variables and secrets and put its reference,
${SECRET_SLOT:<id>}, in the values instead. The editor shows each reference with a lock and the name of the secret it points to, and marks a reference the organisation has no secret for as an error before you save or deploy. Ankra writes the value into a SOPS-encrypted file, so Git never holds the value in plain text, and the cluster decrypts it when it deploys. This needs the organisation’s SOPS encryption: without it, Ankra refuses to save the reference. See Organisation Secrets. - SOPS encryption. When the cluster is connected to Git, declare the value keys to encrypt in the add-on’s
encrypted_paths. Ankra encrypts those values with the organisation’s SOPS key before it writes the values file to Git, keeps the key names readable for diffs, and decrypts them when it deploys. The Stack editor has no field forencrypted_paths: declare it in the cluster YAML, or useankra cluster encrypt. SOPS needs a one-time setup for the organisation; see SOPS.
Operational notes (AGENTS.md)
Every add-on can carry an AGENTS.md: a markdown document of operational learnings, such as upgrade gotchas, a safe rollout order, or values that must stay pinned, that teammates and Ankra AI build up over time. You edit it on the add-on’s Notes tab. The notes are applied with the resource configuration and stored in Git as a plain markdown file, and the Stack editor refuses notes that look like they carry a credential. See Teach Your Agents with AGENTS.md.What the cluster is running
Infrastructure → Clusters → <your cluster> → Add-ons lists every Helm release on the cluster, not only the ones a Stack manages. For each one it shows:
You can filter the list and sort it by name or namespace.
Opening an add-on shows its page:
- Release overview: the Helm chart and version, the Namespace, and Managed by, which links to the owning Stack.
- Running workloads: the Deployments, StatefulSets, DaemonSets, Jobs and CronJobs the release created, with their pods, as the cluster reports them.
- Configuration: the values in two tabs. Saved values are the overrides saved in Ankra, without chart defaults. Installed values are the values the installed release reports, including chart defaults, and may differ from the saved ones. Protected values stay masked, including in YAML and copied text. A badge says whether the saved values reached the release: Saved values applied, Not yet applied, Apply failed or Not reported.
Changing, upgrading and rolling back
An add-on changes the same way as everything else in a Stack: you edit its values or pick a new Pinned chart version in the draft, review the change, and deploy it. In a cluster connected to Git you can also change the values file in the repository; Ankra picks the change up through the repository’s webhook or periodic polling. When the registry has a newer release, the Chart version column on the Add-ons page says so (<version> available). For an add-on a Stack manages, that link opens the Stack editor at the add-on with the new version chosen, so you review and deploy it like any other change.
To roll back, open the Stack and choose More → History and rollback. The page lists every recorded version of each member, who changed it and when, lets you compare two versions, and restores the one you pick. Restoring needs the clusters.operate permission. In a cluster connected to Git, reverting the commit in the repository has the same effect on the next sync.
Add-on settings and Helm values are also readable and changeable through Ankra AI and MCP clients, alongside sync, rollback and uninstall, so routine add-on work can run from chat or your editor. See the MCP Tool Reference. To automate add-on management from your own tooling, see the API Reference.
Related
Stacks
How add-ons, manifests and applications deploy together.
Add-on Catalog
Browse available Helm charts.
Add-on Settings
Deployment, retry and sync settings per add-on.
SOPS Encryption
Encrypt sensitive add-on values in Git.