Variables

Note

Because files can be deployed without a Kubernetes cluster, some built-in variables such as ###ZARF_REGISTRY### may not be available if no previous component has required access to the cluster. If you need one of these built-in variables, a prior component will need to have been called that requires access to the cluster, such as images, repos, manifests, dataInjections.

Deploy-Time Variables and Constants

To use variables and constants at deploy time you need to have two things:

1. a manifest that you want to template a value in
2. a defined variable in the zarf.yaml file from variables or setVariable

The manifest should have your desired variable name in ALL CAPS prefixed with ###ZARF_VAR for variables or prefixed with ###ZARF_CONST for constants and suffixed with ###. For example in a configmap that took a variable named DATABASE_USERNAME you would provide the following:

apiVersion: v1
kind: ConfigMap
metadata:
  name: db-configmap
data:
  username: ###ZARF_VAR_DATABASE_USERNAME###

In the zarf.yaml, you would need to define the variable in the variables section or as output from an action with setVariable with the same name as above. Or for a constant you would use the constants section. For the same example as above, you would have the following for a variable defined by the deploy user:

variables:
  name: DATABASE_USERNAME
  description: 'The username for the database'

And the following for a variable defined as an output from an action:

components:
  - name: set-variable-example
    actions:
      onDeploy:
        after:
          - cmd: echo "username-value"
            setVariables:
              - name: DATABASE_USERNAME

Zarf variables can also have additional fields that describe how Zarf will handle them which are described below:

Field	Type	Description
name *	string	The name to be used for the variable
autoIndent	boolean	Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARF_VAR_.
default	string	The default value to use for the variable
description	string	A description of the variable to be used when prompting the user a value
pattern	string	An optional regex pattern that a variable value must match before a package can be deployed.
prompt	boolean	Whether to prompt the user for input for this variable
sensitive	boolean	Whether to mark this variable as sensitive to not print it in the Zarf log
type	string	Changes the handling of a variable to load contents differently (i.e. from a file rather than as a raw variable - templated files should be kept below 1 MiB)

* Required field
 

Note

Variables with type: file will be set to the filepath in actions due to constraints on the size of environment variables in the shell. This also allows for additional processing of the file by its filename.

Note

The fields default, description and prompt are not available on setVariables since they always take the standard output of an action command and will not be interacted with directly by a deploy user.

Zarf constants are similar but have fewer options as they are static by the time zarf package deploy is run:

Field	Type	Description
value *	string	The value to set for the constant during deploy
name *	string	The name to be used for the constant
autoIndent	boolean	Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARF_CONST_.
description	string	A description of the constant to explain its purpose on package create or deploy confirmation prompts
pattern	string	An optional regex pattern that a constant value must match before a package can be created.

* Required field
 

Note

All names must match the regex pattern ^[A-Z0-9_]+$ Test).

Tip

When not specifying default, prompt, sensitive, autoIndent, or type Zarf will default to default: "", prompt: false, sensitive: false, autoIndent: false, and type: "raw"

For user-specified variables, you can also specify a default value for the variable to take in case a user does not provide one on deploy, and can specify whether to prompt the user for the variable when not using the --confirm or --set flags.

variables:
  name: DATABASE_USERNAME
  default: 'postgres'
  prompt: true

Note

Variables that do not have a default, are not --set and are not prompted for during deploy will be replaced with an empty string in manifests/charts/files

For constants, you must specify the value they will use at package create. These values cannot be overridden with --set during zarf package deploy, but you can use package template variables (described below) to variablize them during zarf package create.

constants:
  name: DATABASE_TABLE
  value: 'users'

Note

zarf package create only templates the zarf.yaml file, and zarf package deploy only templates other manifests, charts and files

Create-Time Package Configuration Templates

You can also specify package configuration templates at package create time by including ###_ZARF_PKG_TMPL_*### as the value for any string-type data in your package definition. These values are discovered during zarf package create and will always be prompted for if not using --confirm or --set. An example of this is below:

kind: ZarfPackageConfig
metadata:
  name: 'pkg-variables'
  description: 'Prompt for a variables during package create'

constants:
  - name: PROMPT_IMAGE
    value: '###ZARF_PKG_TMPL_PROMPT_ON_CREATE###'

components:
  - name: zarf-prompt-image
    required: true
    images:
      - '###ZARF_PKG_TMPL_PROMPT_ON_CREATE###'

Caution

It is not recommended to use package configuration templates for any sensitive data as this will be baked into the package as plain text. Please use a deploy-time variable with the sensitive key set instead.

Note

You can only template string values in this way as non-string values will not marshal/unmarshal properly through the yaml.

Note

You cannot template the component import path using package configuration templates