Deployment Values

Deploy time values are used throughout the Zarf deployment process to template manifests and files, set Helm values, or provide environment variables for actions, and can be provided by the zarf package deploy user, the zarf package create user, or internally by Zarf itself.

Using Values

Value Templates

Values can be templated into manifests, files, and charts using a unique ###ZARF_<VALUE_KEY>### syntax anywhere in the file, where <VALUE_KEY> is the name of the value along with any associated prefix in ALL_CAPS (see Setting Values below). This allows you to punch through other templating engines to place values precisely where you want in a given file. You can also control how this templating happens when defining a value such as with the autoIndent key on constants and variables. A simple value template for a Zarf Variable named DATABASE_USERNAME would look like the following:

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

Helm Chart Mapping

Zarf Variables can also be mapped directly to Helm values within a given charts definition. This is done with the variables key within a chart that allows you to take a Zarf Variable name and map it to a YAML path within that chart’s Helm values. This chart’s Helm value will then be set to the current value of the Zarf Variable at the time of it’s installation.

    charts:
      - name: wordpress
        version: 16.0.4
        namespace: wordpress
        localPath: chart
        variables:
          - name: DATABASE_USERNAME
            path: db.username

Field	Type	Description
path *	string	The path within the Helm chart values where this variable applies
name *	string	The name of the variable
description *	string	A brief description of what the variable controls

* Required field
 

Caution

Chart variables in Zarf are currently an alpha feature and may be subject to change in later versions of Zarf.

Environment Variables

Zarf actions can also pull values from the shell’s environment when running a cmd. These values are available under the same ZARF_<VALUE_KEY> as value templates (without any #s) and can be used like the below:

    actions:
      onDeploy:
        after:
          - cmd: echo ${ZARF_VAR_DATABASE_USERNAME}

Setting Values

Note

All value name fields must match the regex pattern ^[A-Z0-9_]+$ (Test).

Variables (ZARF_VAR_)

Variables are dynamic values that are set by the zarf package deploy user or internally by the outputs of actions. When used they are prefixed with ZARF_VAR, and they can be defined with the top-level variables key for input by the user:

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

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 deployment can continue.
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 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
 

Or can be set within an actions setVariables key to take the value from the standard output of the given cmd:

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

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_.
pattern	string	An optional regex pattern that a variable value must match before a package deployment can continue.
sensitive	boolean	Whether to mark this variable as sensitive to not print it in the 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 when used in actions (see Environment Variables above) due to constraints on the size of environment variables in the shell. This also allows for additional processing of the file by its filename.

Tip

For user-specified variables, you can 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

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

Constants (ZARF_CONST_)

Constants are static values that are set by the zarf package create user and are used as a way to bake in a common value that the package creator would like to template or use within the deployment process. They are useful to centralize the setting of resources that will be baked into the package (such as image references) to have a singular place to update potentially many downstream references. They are set with a top-level constants key as in the below:

constants:
  name: DATABASE_USERNAME
  description: 'The username for the database'
  value: 'postgres'

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
 

Internal Values (ZARF_)

In addition to user supplied Variables, and Constants, Zarf maintains a list of internal variables that components can use for more advanced functionality (such as within init packages). Below are the current values Zarf supports:

• STORAGE_CLASS: Storage class specified for persistent storage within the Kubernetes cluster (maps to --storage-class on zarf init)
• REGISTRY: Address of the registry server used during zarf init (maps to --registry-url on zarf init)
• NODEPORT: Nodeport used for a registry internal to the cluster (maps to --nodeport on zarf init)
• REGISTRY_AUTH_PUSH: Password for pushing images to the registry (maps to --registry-push-password on zarf init)
• REGISTRY_AUTH_PULL: Password for pulling images from the registry (maps to --registry-pull-password on zarf init)
• GIT_PUSH: Username utilized for pushing changes to the Git server (maps to --git-push-username on zarf init)
• GIT_AUTH_PUSH: Password required for pushing changes to the Git server (maps to --git-push-password on zarf init)
• GIT_PULL: Username employed for pulling changes from the Git server (maps to --git-pull-username on zarf init)
• GIT_AUTH_PULL: Password required for pulling changes from the Git server (maps to --git-pull-password on zarf init)
• DATA_INJECTION_MARKER: The marker used within a dataInjection target Pod spec that Zarf uses to track a data injection

Note

Because files can be deployed without a Kubernetes cluster, some built-in values 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 values, a prior component will need to have been called that requires access to the cluster, such as images, repos, charts, manifests, or dataInjections.