Skip to main content
An add-on is a Helm chart that Ankra installs on a cluster and keeps reconciled: an ingress controller, a monitoring tool, a database operator, or a chart you publish yourself. Every add-on belongs to a Stack, next to the manifests and applications it works with, so its values, chart version and dependencies are versioned and deployed together with them.

How an add-on reaches the cluster

  1. 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.
  2. Ankra platform: stores the desired state of the Stack and dispatches the deploy.
  3. Ankra agent: receives the deploy inside your cluster.
  4. Helm release: the agent runs helm upgrade --install with your values. The step succeeds once the release is healthy.
  5. Kubernetes resources: the rendered manifests are applied to the cluster.
This is the native engine, the default for new clusters. Clusters created before it may still use the ArgoCD engine, where an ArgoCD installation in the cluster applies the chart instead; the Stack you build is the same either way. See Deployment Engines for how each engine detects drift and heals it.

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 for encrypted_paths: declare it in the cluster YAML, or use ankra 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.
Edit add-on opens the owning Stack in the editor with this add-on selected; a role that may not edit the Stack sees View stack instead. The More add-on actions menu holds Reapply saved values, which applies the stored configuration to the release again (workloads may restart, and unsaved draft changes are not deployed), and View cluster operations.

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.
A major chart version can carry breaking changes. Read the chart’s release notes, and deploy the new version to a non-production cluster first.
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.

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.