Skip to main content
The same Stack often needs a different domain, replica count or bucket name on each cluster. Variables let you write ${{ ankra.name }} once in your values and manifests and set the actual value on the organisation, a cluster or a Stack. Ankra fills it in when it deploys. How Ankra Works shows where variables sit in the overall model.

Overview

A variable can be set at three levels, and the more specific one wins: Stack > cluster > organisation.
  1. Stack variables - set on one Stack. They win over everything else.
  2. Cluster variables - set on one cluster. They win over organisation variables.
  3. Organisation variables - set once for every cluster and Stack in the organisation.
So a Stack variable named domain_name replaces a cluster or organisation variable of the same name for that Stack only.

Variable Syntax

Reference variables in your stacks using the following syntax:
Examples:

Organisation Variables

Organisation variables apply to every cluster and Stack in the organisation. Use them for values that are the same across your infrastructure. They live under Infrastructure → Variables and secrets (/next/organisation/secrets), in the Variables section. Add variable opens Add a variable, which asks for:
  • Name - letters, numbers and underscores, starting with a letter, for example base_domain or BASE_DOMAIN. The name cannot change later, because Stacks refer to it.
  • Value - the value Stacks receive.
  • Description (optional) - what it is for.
  • Secret - keeps the value out of every list; see Secret variables.
The new variable appears in the list, with when it last changed. A changed value reaches the Stacks that refer to it when they next deploy. Each variable’s menu offers Change… and Delete…, and Ankra shows where a variable is used and where it is overridden.

Common Organisation Variables


Cluster Variables

Cluster variables apply to every Stack on one cluster. Use them for values that differ between environments. They live under Infrastructure → Clusters → <your cluster> → Settings → Variables. Add variable asks for a Name, a Value and an optional Description, with the same naming rules as organisation variables. A cluster variable’s value is kept as plain text, so keep passwords and keys in the organisation’s stored secrets instead (see Secret variables).

Common Cluster Variables


Stack Variables

Stack variables belong to one Stack and have the highest precedence. Use them for values that should override cluster and organisation variables for that Stack only. They are edited in the Stack editor under More → Stack settings, next to the Stack’s description and deploy wave. Like every Stack change, they are saved into the Stack’s draft and take effect when the draft is deployed (see Stacks). A value that looks like a credential is refused: keep secrets in the secret store and reference them by name.

Common Stack Variables

When to Use Stack Variables

Use stack variables when:
  • A specific stack needs values that differ from cluster defaults
  • You want to override cluster or organisation variables for one stack
  • You’re testing different configurations on the same cluster
  • You need stack-specific feature flags or version tags

Secret Variables

An organisation variable marked Secret is kept out of every list: the portal, ankra org variables list and get never show its value. People who may change variables can still show it, and each look is recorded in the audit log. Stacks use it as before.
Marking a variable secret hides its value; it does not encrypt it. The stored value is unchanged, and Ankra reads it to fill in ${{ ankra.<name> }} when a Stack deploys. A cluster variable has no secret setting at all and is kept as plain text.On a cluster connected to a GitOps repository, Ankra fills variables in before it writes the files. The value of a variable, secret or not, is then committed to Git in plain text, unless the key that uses it is listed under encrypted_paths. A Stack variable’s own value is also written in plain text into the cluster’s YAML file, under the Stack’s variables, whatever encrypted_paths says. See SOPS.
For a password, token or key, use an organisation secret instead. Organisation secrets are stored in the Secrets section of the same Variables and secrets page, and their value is shown to no one after you store it, you included. A manifest or add-on value refers to one as ${SECRET_SLOT:<id>}; the Stack editor shows each reference with a lock and the secret’s name, and 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. The Encryption key section of the same page holds the organisation’s SOPS public key and shows the ankra cluster encrypt command that seals a value in a Stack’s manifest before it reaches Git. A sealed value is unreadable without the organisation’s private key. Ankra keeps that key and gives it to the organisation’s clusters, which decrypt sealed values when they deploy; How decryption works says where each deployment engine keeps it.

Using Variables in Stacks

In Manifests

Reference variables anywhere in your Kubernetes manifests:

In Add-on Values

Use variables in Helm chart values:

Built-in Variables

Two names are reserved and resolve from platform state without any variable being created: A stack, cluster, or organisation variable of the same name overrides the built-in. A cluster with no public domain at all leaves the reference literal, which an Ingress host rejects loudly rather than resolving to nothing.

Variable Resolution

When you deploy a stack, Ankra resolves variables in this order:
  1. Check for a matching stack variable (highest priority)
  2. If not found, check for a matching cluster variable
  3. If not found, check for a matching organisation variable
  4. If still not found, the literal ${{ ankra.variable_name }} is left in place (which will likely cause deployment errors)
This precedence allows you to define sensible defaults at the organisation level, environment-specific overrides at the cluster level, and stack-specific customizations when needed.

Managing Variables

Deleting Variables

After you delete a variable that Stacks use, their next deploy carries the literal ${{ ankra.<name> }} where its value was, until you add it back. A cluster variable’s Stacks fall back to an organisation variable of the same name when there is one. Deleting cannot be undone.
Before you delete an organisation variable, check where it is used and where it is overridden. Delete… in the variable’s menu asks you to confirm with Delete variable.

Variable Naming Rules

Variable names must follow these rules:
  • Start with a letter (a-z, A-Z)
  • Contain only letters, numbers, and underscores
  • Be unique within their scope (organisation, cluster or Stack)
Valid names: domain_name, API_KEY, replica_count_v2 Invalid names: 123_name, my-variable, name with spaces

Managing variables via API and CLI

All three scopes can be managed over the API and the Ankra CLI, so you can manage them from scripts and pipelines as well as the portal.

CLI

set is an upsert, and - reads the value from stdin. Without --secret, set creates a plain variable (an update keeps the variable’s current setting), and every role that can read variables, Viewer included, can read a plain variable’s value, so add --secret for anything sensitive, or store it as an organisation secret. reveal reads a secret variable back for people who may change variables, and every reveal is audited. See the CLI reference for the full command set.

REST API

Organisation and cluster variables expose the same list, create, update and delete shape under /api/v1/org/variables (organisation) and /api/v1/org/clusters/imported/{cluster_id}/variables (cluster). A Stack’s variables are read and changed together with GET and PATCH on /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/variables, and one at a time with PUT and DELETE on /api/v1/org/clusters/imported/{cluster_id}/stacks/{stack_name}/variables/{variable_name}. All of them take a bearer token. See the API Reference for schemas.

AI Prompts

Ask Ankra AI with prompts such as these:

Stacks

Build stacks that use variables.

SOPS Encryption

Encrypt sensitive values in Git.

Organisation Settings

Configure organisation-level settings.

Cluster Settings

Configure cluster-level settings and variables.