Skip to main content

Zarf Package Schema

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfPackage
kind *
 

Required

Description: The kind of Zarf package

Typeenum (of string)
Default"ZarfPackageConfig"
note

Must be one of:

  • "ZarfInitConfig"
  • "ZarfPackageConfig"
metadata
 

metadata

Description: Package metadata

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfMetadata
name *
 

Required

Description: Name to identify this Zarf package

Typestring
Restrictions
Must match regular expression^[a-z0-9\-]+$ Test
description
 

Description: Additional information about this package

Typestring
version
 

Description: Generic string set by a package author to track the package version (Note: ZarfInitConfigs will always be versioned to the CLIVersion they were created with)

Typestring
url
 

Description: Link to package information when online

Typestring
image
 

Description: An image URL to embed in this package (Reserved for future use in Zarf UI)

Typestring
uncompressed
 

Description: Disable compression of this package

Typeboolean
architecture
 

Description: The target cluster architecture for this package

Typestring

Examples:

"arm64", "amd64"
yolo
 

Description: Yaml OnLy Online (YOLO): True enables deploying a Zarf package without first running zarf init against the cluster. This is ideal for connected environments where you want to use existing VCS and container registries.

Typeboolean
authors
 

Description: Comma-separated list of package authors (including contact info)

Typestring

Example:

"Doug <hello@defenseunicorns.com>, Pepr <hello@defenseunicorns.com>"
documentation
 

Description: Link to package documentation when online

Typestring
source
 

Description: Link to package source code when online

Typestring
vendor
 

Description: Name of the distributing entity, organization or individual.

Typestring
aggregateChecksum
 

Description: Checksum of a checksums.txt file that contains checksums all the layers within the package.

Typestring
build
 

build

Description: Zarf-generated package build data

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfBuildData
terminal *
 

Required

Description: The machine name that created this package

Typestring
user *
 

Required

Description: The username who created this package

Typestring
architecture *
 

Required

Description: The architecture this package was created on

Typestring
timestamp *
 

Required

Description: The timestamp when this package was created

Typestring
version *
 

Required

Description: The version of Zarf used to build this package

Typestring
migrations
 

Description: Any migrations that have been run on this package

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

migrations items

Typestring
differential
 

Description: Whether this package was created with differential components

Typeboolean
registryOverrides
 

build > registryOverrides

Description: Any registry domains that were overridden on package create when pulling images

Typeobject
Additional propertiesAny type: allowed
Pattern Property .*
 
note

All properties whose name matches the regular expression .* (Test) must respect the following conditions

Typestring
differentialMissing
 

Description: List of components that were not included in this package due to differential packaging

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

differentialMissing items

Typestring
OCIImportedComponents
 

build > OCIImportedComponents

Description: Map of components that were imported via OCI. The keys are OCI Package URLs and values are the component names

Typeobject
Additional propertiesAny type: allowed
Pattern Property .*
 
note

All properties whose name matches the regular expression .* (Test) must respect the following conditions

Typestring
lastNonBreakingVersion
 

Description: The minimum version of Zarf that does not have breaking package structure changes

Typestring
components *
 

components

Required

Description: List of components to deploy in this package

Typearray

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

ZarfComponent

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponent
name *
 

Required

Description: The name of the component

Typestring
Restrictions
Must match regular expression^[a-z0-9\-]+$ Test
description
 

Description: Message to include during package deploy describing the purpose of this component

Typestring
default
 

Description: Determines the default Y/N state for installing this component on package deploy

Typeboolean
required
 

Description: Do not prompt user to install this component

Typeboolean
only
 

components > only

Description: Filter when this component is included in package creation or deployment

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentOnlyTarget
localOS
 

Description: Only deploy component to specified OS

Typeenum (of string)
note

Must be one of:

  • "linux"
  • "darwin"
  • "windows"
cluster
 

components > only > cluster

Description: Only deploy component to specified clusters

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentOnlyCluster
architecture
 

Description: Only create and deploy to clusters of the given architecture

Typeenum (of string)
note

Must be one of:

  • "amd64"
  • "arm64"
distros
 

Description: A list of kubernetes distros this package works with (Reserved for future use)

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

distros items

Typestring
import
 

components > import

Description: Import a component from another Zarf package

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentImport
name
 

Description: The name of the component to import from the referenced zarf.yaml

Typestring
path
 

Description: The relative path to a directory containing a zarf.yaml to import from

Typestring
Restrictions
Must match regular expression^(?!.*###ZARF_PKG_TMPL_).*$ Test
url
 

Description: [beta] The URL to a Zarf package to import via OCI

Typestring
Restrictions
Must match regular expression^oci://(?!.*###ZARF_PKG_TMPL_).*$ Test
files
 

components > files

Description: Files or folders to place on disk during package deployment

Typearray

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

ZarfFile

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfFile
source *
 

Required

Description: Local folder or file path or remote URL to pull into the package

Typestring
shasum
 

Description: (files only) Optional SHA256 checksum of the file

Typestring
target *
 

Required

Description: The absolute or relative path where the file or folder should be copied to during package deploy

Typestring
executable
 

Description: (files only) Determines if the file should be made executable during package deploy

Typeboolean
symlinks
 

Description: List of symlinks to create during package deploy

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

Typestring
extractPath
 

Description: Local folder or file to be extracted from a 'source' archive

Typestring
charts
 

components > charts

Description: Helm charts to install during package deploy

Typearray

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

ZarfChart

Typecombining
Additional propertiesNot allowed
Defined in#/definitions/ZarfChart
One of(Option)
url
localPath

Property url

Title: url

Typeobject
Additional propertiesAny type: allowed

The following properties are required

  • url

Property localPath

Title: localPath

Typeobject
Additional propertiesAny type: allowed

The following properties are required

  • localPath
name *
 

Required

Description: The name of the chart to deploy; this should be the name of the chart as it is installed in the helm repo

Typestring
releaseName
 

Description: The name of the release to create; defaults to the name of the chart

Typestring
url
 

Description: The URL of the OCI registry, chart repository, or git repo where the helm chart is stored

Typestring

Examples:

"OCI registry: oci://ghcr.io/stefanprodan/charts/podinfo", "helm chart repo: https://stefanprodan.github.io/podinfo", "git repo: https://github.com/stefanprodan/podinfo"
version
 

Description: The version of the chart to deploy; for git-based charts this is also the tag of the git repo

Typestring
namespace *
 

Required

Description: The namespace to deploy the chart to

Typestring
valuesFiles
 

Description: List of local values file paths or remote URLs to include in the package; these will be merged together

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

valuesFiles items

Typestring
gitPath
 

Description: The path to the chart in the repo if using a git repo instead of a helm repo

Typestring

Example:

"charts/your-chart"
localPath
 

Description: The path to the chart folder

Typestring
noWait
 

Description: Whether to not wait for chart resources to be ready before continuing

Typeboolean
manifests
 

components > manifests

Description: Kubernetes manifests to be included in a generated Helm chart on package deploy

Typearray

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

ZarfManifest

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfManifest
name *
 

Required

Description: A name to give this collection of manifests; this will become the name of the dynamically-created helm chart

Typestring
namespace
 

Description: The namespace to deploy the manifests to

Typestring
files
 

Description: List of local K8s YAML files or remote URLs to deploy (in order)

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

files items

Typestring
kustomizeAllowAnyDirectory
 

Description: Allow traversing directory above the current directory if needed for kustomization

Typeboolean
kustomizations
 

Description: List of local kustomization paths or remote URLs to include in the package

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

kustomizations items

Typestring
noWait
 

Description: Whether to not wait for manifest resources to be ready before continuing

Typeboolean
images
 

Description: List of OCI images to include in the package

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

images items

Typestring
repos
 

Description: List of git repos to include in the package

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

repos items

Typestring
dataInjections
 

components > dataInjections

Description: Datasets to inject into a container in the target cluster

Typearray

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

ZarfDataInjection

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfDataInjection
source *
 

Required

Description: Either a path to a local folder/file or a remote URL of a file to inject into the given target pod + container

Typestring
target *
 

components > dataInjections > target

Required

Description: The target pod + container to inject the data into

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfContainerTarget
namespace *
 

Required

Description: The namespace to target for data injection

Typestring
selector *
 

Required

Description: The K8s selector to target for data injection

Typestring

Example:

"app=data-injection"
container *
 

Required

Description: The container name to target for data injection

Typestring
path *
 

Required

Description: The path within the container to copy the data into

Typestring
compress
 

Description: Compress the data before transmitting using gzip. Note: this requires support for tar/gzip locally and in the target image.

Typeboolean
extensions
 

components > extensions

Description: Extend component functionality with additional features

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentExtensions
bigbang
 

components > extensions > bigbang

Description: Configurations for installing Big Bang and Flux in the cluster

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/BigBang
version *
 

Required

Description: The version of Big Bang to use

Typestring
repo
 

Description: Override repo to pull Big Bang from instead of Repo One

Typestring
valuesFiles
 

Description: The list of values files to pass to Big Bang; these will be merged together

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

valuesFiles items

Typestring
skipFlux
 

Description: Whether to skip deploying flux; Defaults to false

Typeboolean
fluxPatchFiles
 

Description: Optional paths to Flux kustomize strategic merge patch files

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

fluxPatchFiles items

Typestring
actions
 

components > actions

Description: Custom commands to run at various stages of a package lifecycle

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentActions
onCreate
 

components > actions > onCreate

Description: Actions to run during package creation

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentActionSet
defaults
 

components > actions > onCreate > defaults

Description: Default configuration for all actions in this set

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentActionDefaults
mute
 

Description: Hide the output of commands during execution (default false)

Typeboolean
maxTotalSeconds
 

Description: Default timeout in seconds for commands (default to 0

Typeinteger
maxRetries
 

Description: Retry commands given number of times if they fail (default 0)

Typeinteger
dir
 

Description: Working directory for commands (default CWD)

Typestring
env
 

Description: Additional environment variables for commands

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

env items

Typestring
shell
 

components > actions > onCreate > defaults > shell

Description: (cmd only) Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentActionShell
windows
 

Description: (default 'powershell') Indicates a preference for the shell to use on Windows systems (note that choosing 'cmd' will turn off migrations like touch -> New-Item)

Typestring

Examples:

"powershell", "cmd", "pwsh", "sh", "bash", "gsh"
linux
 

Description: (default 'sh') Indicates a preference for the shell to use on Linux systems

Typestring

Examples:

"sh", "bash", "fish", "zsh", "pwsh"
darwin
 

Description: (default 'sh') Indicates a preference for the shell to use on macOS systems

Typestring

Examples:

"sh", "bash", "fish", "zsh", "pwsh"
before
 

components > actions > onCreate > before

Description: Actions to run at the start of an operation

Typearray

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

ZarfComponentAction

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentAction
mute
 

Description: Hide the output of the command during package deployment (default false)

Typeboolean
maxTotalSeconds
 

Description: Timeout in seconds for the command (default to 0

Typeinteger
maxRetries
 

Description: Retry the command if it fails up to given number of times (default 0)

Typeinteger
dir
 

Description: The working directory to run the command in (default is CWD)

Typestring
env
 

Description: Additional environment variables to set for the command

Typearray of string

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

env items

Typestring
cmd
 

Description: The command to run. Must specify either cmd or wait for the action to do anything.

Typestring
shell
 

components > actions > onCreate > before > shell

Description: (cmd only) Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems

Typeobject
Additional propertiesNot allowed
Same definition asshell
setVariables
 

components > actions > onCreate > before > setVariables

Description: (onDeploy/cmd only) An array of variables to update with the output of the command. These variables will be available to all remaining actions and components in the package.

Typearray

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

ZarfComponentActionSetVariable

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentActionSetVariable
name *
 

Required

Description: The name to be used for the variable

Typestring
Restrictions
Must match regular expression^[A-Z0-9_]+$ Test
sensitive
 

Description: Whether to mark this variable as sensitive to not print it in the Zarf log

Typeboolean
autoIndent
 

Description: Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARFVAR.

Typeboolean
pattern
 

Description: An optional regex pattern that a variable value must match before a package deployment can continue.

Typestring
type
 

Description: 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)

Typeenum (of string)
note

Must be one of:

  • "raw"
  • "file"
description
 

Description: Description of the action to be displayed during package execution instead of the command

Typestring
wait
 

components > actions > onCreate > before > wait

Description: Wait for a condition to be met before continuing. Must specify either cmd or wait for the action. See the 'zarf tools wait-for' command for more info.

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentActionWait
cluster
 

components > actions > onCreate > before > wait > cluster

Description: Wait for a condition to be met in the cluster before continuing. Only one of cluster or network can be specified.

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentActionWaitCluster
kind *
 

Required

Description: The kind of resource to wait for

Typestring

Examples:

"Pod", "Deployment)"
name *
 

Required

Description: The name of the resource or selector to wait for

Typestring

Examples:

"podinfo", "app=podinfo"
namespace
 

Description: The namespace of the resource to wait for

Typestring
condition
 

Description: The condition or jsonpath state to wait for; defaults to exist

Typestring

Examples:

"Ready", "Available"
network
 

components > actions > onCreate > before > wait > network

Description: Wait for a condition to be met on the network before continuing. Only one of cluster or network can be specified.

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfComponentActionWaitNetwork
protocol *
 

Required

Description: The protocol to wait for

Typeenum (of string)
note

Must be one of:

  • "tcp"
  • "http"
  • "https"
address *
 

Required

Description: The address to wait for

Typestring

Examples:

"localhost:8080", "1.1.1.1"
code
 

Description: The HTTP status code to wait for if using http or https

Typeinteger

Examples:

200, 404
after
 

components > actions > onCreate > after

Description: Actions to run at the end of an operation

Typearray

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

ZarfComponentAction

Typeobject
Additional propertiesNot allowed
Same definition ascomponents_items_actions_onCreate_before_items
onSuccess
 

components > actions > onCreate > onSuccess

Description: Actions to run if all operations succeed

Typearray

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

ZarfComponentAction

Typeobject
Additional propertiesNot allowed
Same definition ascomponents_items_actions_onCreate_before_items
onFailure
 

components > actions > onCreate > onFailure

Description: Actions to run if all operations fail

Typearray

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

ZarfComponentAction

Typeobject
Additional propertiesNot allowed
Same definition ascomponents_items_actions_onCreate_before_items
onDeploy
 

components > actions > onDeploy

Description: Actions to run during package deployment

Typeobject
Additional propertiesNot allowed
Same definition asonCreate
onRemove
 

components > actions > onRemove

Description: Actions to run during package removal

Typeobject
Additional propertiesNot allowed
Same definition asonCreate
constants
 

constants

Description: Constant template values applied on deploy for K8s resources

Typearray

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

ZarfPackageConstant

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfPackageConstant
name *
 

Required

Description: The name to be used for the constant

Typestring
Restrictions
Must match regular expression^[A-Z0-9_]+$ Test
value *
 

Required

Description: The value to set for the constant during deploy

Typestring
description
 

Description: A description of the constant to explain its purpose on package create or deploy confirmation prompts

Typestring
autoIndent
 

Description: Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARFCONST.

Typeboolean
pattern
 

Description: An optional regex pattern that a constant value must match before a package can be created.

Typestring
variables
 

variables

Description: Variable template values applied on deploy for K8s resources

Typearray

Min Items: N/A Max Items: N/A Item unicity: False Additional items: N/A

ZarfPackageVariable

Typeobject
Additional propertiesNot allowed
Defined in#/definitions/ZarfPackageVariable
name *
 

Required

Description: The name to be used for the variable

Typestring
Restrictions
Must match regular expression^[A-Z0-9_]+$ Test
description
 

Description: A description of the variable to be used when prompting the user a value

Typestring
default
 

Description: The default value to use for the variable

Typestring
prompt
 

Description: Whether to prompt the user for input for this variable

Typeboolean
sensitive
 

Description: Whether to mark this variable as sensitive to not print it in the Zarf log

Typeboolean
autoIndent
 

Description: Whether to automatically indent the variable's value (if multiline) when templating. Based on the number of chars before the start of ###ZARFVAR.

Typeboolean
pattern
 

Description: An optional regex pattern that a variable value must match before a package can be deployed.

Typestring
type
 

Description: 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)

Typeenum (of string)
note

Must be one of:

  • "raw"
  • "file"

Generated from zarf.schema.json