This example demonstrates how to define
constants in your package that will be templated across the manifests and charts your package uses during
zarf package deploy with
###ZARF_CONST_*###, and also shows how package configuration templates can be used in the
zarf package create with
With these variables and templating features, you can define values in the
zarf.yaml file without having to set them manually in every manifest and chart, and can prompt the deploy user for certain information you may want to make dynamic on
zarf package deploy.
This becomes useful when you are working with an upstream chart that is often changing, or a lot of charts that have slightly different conventions for their values. Now you can standardize all of that from your
Text files are also templated during
zarf package deploy so you can use these variables in any text file that you want to be templated.
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
Deploy-Time Variables and Constants
To use variables and constants at deploy time you need to have two things:
- a manifest that you want to template a value in
- a defined variable in the
The manifest should have your desired variable name in ALL CAPS prefixed with
variables or prefixed with
constants and suffixed with
###. For example in a configmap that took a variable named
DATABASE_USERNAME you would provide the following:
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:
description: 'The username for the database'
And the following for a variable defined as an output from an action:
- name: set-variable-example
- cmd: echo "username-value"
- name: DATABASE_USERNAME
variables can also have additional fields that describe how Zarf will handle them which are described below:
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.
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.
constants are similar but have fewer options as they are static by the time
zarf package deploy is run:
All names must match the regex pattern
When not specifying
type Zarf will default to
autoIndent: false, and
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
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
zarf package deploy, but you can use package template variables (described below) to variablize them during
zarf package create.
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
--set. An example of this is below:
description: 'Prompt for a variables during package create'
- name: PROMPT_IMAGE
- name: zarf-prompt-image
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.
You can only template string values in this way as non-string values will not marshal/unmarshal properly through the yaml.
If you use
--confirm and do not
--set all of the package configuration templates you will receive an error
You cannot template the component import path using package configuration templates
To view the example in its entirety, select the
Edit this page link below the article and select the parent folder.