Zarf Package Schema

Type	object
Additional properties
Defined in	#/definitions/ZarfPackage

kind *

 

Description: The kind of Zarf package

Type	enum (of string)
Default	"ZarfPackageConfig"

note

Must be one of:

• "ZarfInitConfig"
• "ZarfPackageConfig"

metadata

 

metadata

Description: Package metadata

Type	object
Additional properties
Defined in	#/definitions/ZarfMetadata

name *

 

Description: Name to identify this Zarf package

Type	string

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

description

 

Description: Additional information about this package

Type	string

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)

Type	string

url

 

Description: Link to package information when online

Type	string

image

 

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

Type	string

uncompressed

 

Description: Disable compression of this package

Type	boolean

architecture

 

Description: The target cluster architecture for this package

Type	string

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.

Type	boolean

authors

 

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

Type	string

Example:

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

documentation

 

Description: Link to package documentation when online

Type	string

source

 

Description: Link to package source code when online

Type	string

vendor

 

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

Type	string

aggregateChecksum

 

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

Type	string

build

 

build

Description: Zarf-generated package build data

Type	object
Additional properties
Defined in	#/definitions/ZarfBuildData

terminal *

 

Description: The machine name that created this package

Type	string

user *

 

Description: The username who created this package

Type	string

architecture *

 

Description: The architecture this package was created on

Type	string

timestamp *

 

Description: The timestamp when this package was created

Type	string

version *

 

Description: The version of Zarf used to build this package

Type	string

migrations

 

Description: Any migrations that have been run on this package

Type	array of string

migrations items

Type	string

differential

 

Description: Whether this package was created with differential components

Type	boolean

registryOverrides

 

build > registryOverrides

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

Type	object
Additional properties

Pattern Property .*

 

note

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

Type	string

differentialMissing

 

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

Type	array of string

differentialMissing items

Type	string

OCIImportedComponents

 

build > OCIImportedComponents

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

Type	object
Additional properties

Pattern Property .*

 

note

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

Type	string

lastNonBreakingVersion

 

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

Type	string

components *

 

components

Description: List of components to deploy in this package

Type	array

ZarfComponent

Type	object
Additional properties
Defined in	#/definitions/ZarfComponent

name *

 

Description: The name of the component

Type	string

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

description

 

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

Type	string

default

 

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

Type	boolean

required

 

Description: Do not prompt user to install this component

Type	boolean

only

 

components > only

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

Type	object
Additional properties
Defined in	#/definitions/ZarfComponentOnlyTarget

localOS

 

Description: Only deploy component to specified OS

Type	enum (of string)

note

Must be one of:

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

cluster

 

components > only > cluster

Description: Only deploy component to specified clusters

Type	object
Additional properties
Defined in	#/definitions/ZarfComponentOnlyCluster

architecture

 

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

Type	enum (of string)

note

Must be one of:

• "amd64"
• "arm64"

distros

 

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

Type	array of string

distros items

Type	string

import

 

components > import

Description: Import a component from another Zarf package

Type	object
Additional properties
Defined in	#/definitions/ZarfComponentImport

name

 

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

Type	string

path

 

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

Type	string

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

url

 

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

Type	string

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

files

 

components > files

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

Type	array

ZarfFile

Type	object
Additional properties
Defined in	#/definitions/ZarfFile

source *

 

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

Type	string

shasum

 

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

Type	string

target *

 

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

Type	string

executable

 

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

Type	boolean

symlinks

 

Description: List of symlinks to create during package deploy

Type	array of string

symlinks items

Type	string

extractPath

 

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

Type	string

charts

 

components > charts

Description: Helm charts to install during package deploy

Type	array

ZarfChart

Type	combining
Additional properties
Defined in	#/definitions/ZarfChart

One of(Option)
url
localPath

Property url

Title: url

Type	object
Additional properties

The following properties are required

• url

Property localPath

Title: localPath

Type	object
Additional properties

The following properties are required

• localPath

name *

 

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

Type	string

releaseName

 

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

Type	string

url

 

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

Type	string

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

Type	string

namespace *

 

Description: The namespace to deploy the chart to

Type	string

valuesFiles

 

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

Type	array of string

valuesFiles items

Type	string

gitPath

 

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

Type	string

Example:

"charts/your-chart"

localPath

 

Description: The path to the chart folder

Type	string

noWait

 

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

Type	boolean

manifests

 

components > manifests

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

Type	array

ZarfManifest

Type	object
Additional properties
Defined in	#/definitions/ZarfManifest

name *

 

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

Type	string

namespace

 

Description: The namespace to deploy the manifests to

Type	string

files

 

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

Type	array of string

files items

Type	string

kustomizeAllowAnyDirectory

 

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

Type	boolean

kustomizations

 

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

Type	array of string

kustomizations items

Type	string

noWait

 

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

Type	boolean

images

 

Description: List of OCI images to include in the package

Type	array of string

images items

Type	string

repos

 

Description: List of git repos to include in the package

Type	array of string

repos items

Type	string

dataInjections

 

components > dataInjections

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

Type	array

ZarfDataInjection

Type	object
Additional properties
Defined in	#/definitions/ZarfDataInjection

source *

 

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

Type	string

target *

 

components > dataInjections > target

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

Type	object
Additional properties
Defined in	#/definitions/ZarfContainerTarget

namespace *

 

Description: The namespace to target for data injection

Type	string

selector *

 

Description: The K8s selector to target for data injection

Type	string

Example:

"app=data-injection"

container *

 

Description: The container name to target for data injection

Type	string

path *

 

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

Type	string

compress

 

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

Type	boolean

extensions

 

components > extensions

Description: Extend component functionality with additional features

Type	object
Additional properties
Defined in	#/definitions/ZarfComponentExtensions

bigbang

 

components > extensions > bigbang

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

Type	object
Additional properties
Defined in	#/definitions/BigBang

version *

 

Description: The version of Big Bang to use

Type	string

repo

 

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

Type	string

valuesFiles

 

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

Type	array of string

valuesFiles items

Type	string

skipFlux

 

Description: Whether to skip deploying flux; Defaults to false

Type	boolean

fluxPatchFiles

 

Description: Optional paths to Flux kustomize strategic merge patch files

Type	array of string

fluxPatchFiles items

Type	string

actions

 

components > actions

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

Type	object
Additional properties
Defined in	#/definitions/ZarfComponentActions

onCreate

 

components > actions > onCreate

Description: Actions to run during package creation

Type	object
Additional properties
Defined in	#/definitions/ZarfComponentActionSet

defaults

 

components > actions > onCreate > defaults

Description: Default configuration for all actions in this set

Type	object
Additional properties
Defined in	#/definitions/ZarfComponentActionDefaults

mute

 

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

Type	boolean

maxTotalSeconds

 

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

Type	integer

maxRetries

 

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

Type	integer

dir

 

Description: Working directory for commands (default CWD)

Type	string

env

 

Description: Additional environment variables for commands

Type	array of string

env items

Type	string

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

Type	object
Additional properties
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)

Type	string

Examples:

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

linux

 

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

Type	string

Examples:

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

darwin

 

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

Type	string

Examples:

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

before

 

components > actions > onCreate > before

Description: Actions to run at the start of an operation

Type	array

ZarfComponentAction

Type	object
Additional properties
Defined in	#/definitions/ZarfComponentAction

mute

 

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

Type	boolean

maxTotalSeconds

 

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

Type	integer

maxRetries

 

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

Type	integer

dir

 

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

Type	string

env

 

Description: Additional environment variables to set for the command

Type	array of string

env items

Type	string

cmd

 

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

Type	string

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

Type	object
Additional properties
Same definition as	shell

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.

Type	array

ZarfComponentActionSetVariable

Type	object
Additional properties
Defined in	#/definitions/ZarfComponentActionSetVariable

name *

 

Description: The name to be used for the variable

Type	string

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

Type	boolean

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.

Type	boolean

pattern

 

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

Type	string

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)

Type	enum (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

Type	string

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.

Type	object
Additional properties
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.

Type	object
Additional properties
Defined in	#/definitions/ZarfComponentActionWaitCluster

kind *

 

Description: The kind of resource to wait for

Type	string

Examples:

"Pod", "Deployment)"

name *

 

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

Type	string

Examples:

"podinfo", "app=podinfo"

namespace

 

Description: The namespace of the resource to wait for

Type	string

condition

 

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

Type	string

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.

Type	object
Additional properties
Defined in	#/definitions/ZarfComponentActionWaitNetwork

protocol *

 

Description: The protocol to wait for

Type	enum (of string)

note

Must be one of:

• "tcp"
• "http"
• "https"

address *

 

Description: The address to wait for

Type	string

Examples:

"localhost:8080", "1.1.1.1"

code

 

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

Type	integer

Examples:

200, 404

after

 

components > actions > onCreate > after

Description: Actions to run at the end of an operation

Type	array

ZarfComponentAction

Type	object
Additional properties
Same definition as	components_items_actions_onCreate_before_items

onSuccess

 

components > actions > onCreate > onSuccess

Description: Actions to run if all operations succeed

Type	array

ZarfComponentAction

Type	object
Additional properties
Same definition as	components_items_actions_onCreate_before_items

onFailure

 

components > actions > onCreate > onFailure

Description: Actions to run if all operations fail

Type	array

ZarfComponentAction

Type	object
Additional properties
Same definition as	components_items_actions_onCreate_before_items

onDeploy

 

components > actions > onDeploy

Description: Actions to run during package deployment

Type	object
Additional properties
Same definition as	onCreate

onRemove

 

components > actions > onRemove

Description: Actions to run during package removal

Type	object
Additional properties
Same definition as	onCreate

constants

 

constants

Description: Constant template values applied on deploy for K8s resources

Type	array

ZarfPackageConstant

Type	object
Additional properties
Defined in	#/definitions/ZarfPackageConstant

name *

 

Description: The name to be used for the constant

Type	string

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

value *

 

Description: The value to set for the constant during deploy

Type	string

description

 

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

Type	string

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.

Type	boolean

pattern

 

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

Type	string

variables

 

variables

Description: Variable template values applied on deploy for K8s resources

Type	array

ZarfPackageVariable

Type	object
Additional properties
Defined in	#/definitions/ZarfPackageVariable

name *

 

Description: The name to be used for the variable

Type	string

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

Type	string

default

 

Description: The default value to use for the variable

Type	string

prompt

 

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

Type	boolean

sensitive

 

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

Type	boolean

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.

Type	boolean

pattern

 

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

Type	string

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)

Type	enum (of string)

note

Must be one of:

• "raw"
• "file"

---

Generated from zarf.schema.json