Config Files

Users can use a config file to easily control flags for zarf init, zarf package create, and zarf package deploy commands, as well as global flags (excluding --confirm), enabling a more straightforward and declarative workflow.

Zarf supports config files written in toml and yaml. By default Zarf will look for a file called zarf-config with one of these filenames in the current working directory. To generate a blank config file you can run zarf dev generate-config with an optional output filename/format. For example, to create an empty config file with the my-cool-env in the yaml format, you can use zarf dev generate-config my-cool-env.yaml.

To use a custom config filename, set the ZARF_CONFIG environment variable to the config file’s path. For example, to use the my-cool-env.yaml config file in the current working directory, you can set the ZARF_CONFIG environment variable to my-cool-env.yaml. The ZARF_CONFIG environment variable can be set either in the shell or in a .env file in the current working directory. Note that the ZARF_CONFIG environment variable takes precedence over the default config file path.

Additionally, you can set any supported config parameter via an environment variable using the ZARF_ prefix. For example, you can set the zarf init --storage-class flag by setting the ZARF_INIT_STORAGE_CLASS environment variable. Note that the ZARF_ environment variable takes precedence over a config file.

While config files set default values, these values can still be overwritten by command line flags. For example, if the config file sets the log level to info and the command line flag is set to debug, the log level will be set to debug. The order of precedence for command line configuration is as follows:

1. Command line flags
2. Environment variables
3. Config file
4. Default values

Config File Location

Zarf searches for the Zarf Config File from either your current working directory or the ~/.zarf/ directory if you don’t specify a config file.

Config File Examples

yaml

zarf-config.yaml

# Example config file, use "zarf prepare generate-config zarf-config.yaml" to generate a new one
log_level : 'info'

package:
  create:
    skip_sbom : false
    set:
      zebra : 'stripes'
      leopard : 'spots'
  deploy:
    components: 'lion'
    values:
      - deploy-values.yaml

toml

zarf-config.toml

# Example config file, use "zarf prepare generate-config" to generate a new one
log_level = 'info'

[package]
[package.create]
skip_sbom = false

[package.create.set]
zebra = 'stripes'
leopard = 'spots'

[package.deploy]
components = 'lion'
values = ['deploy-values.yaml']

Example Package

export ZARF_CONFIG=examples/config-file/zarf-config.yaml

zarf package create examples/config-file --confirm

# replace <arch> with your system architecture
zarf package deploy zarf-package-config-file-<arch>.tar.zst --confirm

zarf.yaml

kind: ZarfPackageConfig
metadata:
  name: config-file
  description: Test component to demonstrate using a config file to control the cli. Files are generated using "zarf prepare generate-config"

values:
  files:
    - values.yaml

components:
  - name: lion
    description: By default, only this component will be deployed when using the config file
    required: true
    manifests:
      - name: config-example-configmap
        template: true
        files:
          - simple-configmap.yaml

  - name: zebra
    # Notice this string is wrapped in quotes, as Zarf package templates use #### as a delimiter, which is also used in YAML for comments
    description: "This is a zebra and they have ###ZARF_PKG_TMPL_ZEBRA###"

  - name: leopard
    description: "This is a leopard and they have ###ZARF_PKG_TMPL_LEOPARD###"