v1beta1 Package

JSON Schema source

ZarfPackage

Package is the top-level structure of a Zarf package definition.

apiVersion (string), required — One of: "zarf.dev/v1beta1"
The API version of the Zarf package.
components ([]Component), required — Min items: 1
List of components to deploy in this package.
kind (string), required — One of: "ZarfInitConfig", "ZarfPackageConfig"; Default: "ZarfPackageConfig"
The kind of Zarf package.
attachments (map[string]string)
Attachments are files included in the package.
build (BuildData)
Zarf-generated package build data.
metadata (PackageMetadata)
Package metadata.
values (Values)
Values imports Zarf values files for templating and overriding Helm values.

BuildData

BuildData is written during package create to track details of the created package.

aggregateChecksum (string), required
Checksum of a checksums.txt file that contains checksums all the layers within the package.
architecture (string), required
The architecture this package was created on.
version (string), required
The version of Zarf used to build this package.
differential (Differential)
Base package used to create this differential package. Omitted for full packages.
flavor (string)
The flavor of Zarf used to build this package.
hostname (string)
The machine name that created this package.
migrations ([]string)
Any migrations that have been run on this package.
provenanceFiles ([]string)
ProvenanceFiles lists files present in the package that are not included in checksums.txt. These are files added after checksum generation (e.g., signature files).
registryOverrides (map[string]string)
Any registry domains that were overridden on package create when pulling images.
signed (boolean)
Whether this package was signed.
timestamp (string)
The timestamp when this package was created.
user (string)
The username who created this package.
versionRequirements ([]VersionRequirement)
Requirements for specific Zarf versions needed to deploy this package.

Component

Component is the primary functional grouping of assets to deploy by Zarf.

name (string), required — Pattern: ^[a-z0-9][a-z0-9\-]*$
The name of the component.
actions (ComponentActions)
Custom commands to run at various stages of a package lifecycle.
charts ([]Chart)
Helm charts to install during package deploy.
description (string)
Message to include during package deploy describing the purpose of this component.
files ([]File)
Files or folders to place on disk during package deployment.
imageArchives ([]ImageArchive)
List of tar archives of images to include in the package.
images ([]Image)
List of OCI images to include in the package.
import (ComponentImport)
Import a component from another Zarf component config.
manifests ([]Manifest)
Kubernetes manifests to be included in a generated Helm chart on package deploy.
optional (boolean)
Do not install this component unless explicitly requested. Defaults to false, meaning the component is required.
repositories ([]Repository)
List of git repositories to include in the package.
selector (ComponentSelector)
Filter when this component is included during package creation based on architecture or flavor.
service (Service)
The Zarf CLI service this component provides, such as the registry, injector, or agent.
stateAccess ([]string)
Groups of sensitive .State fields this component may access in Go templates (manifests, files, actions with template: true). Valid values: "registryCredentials", "gitCredentials", "agentCerts".
target (ComponentTarget)
Filter when this component is deployed based on OS.

PackageMetadata

PackageMetadata holds information about the package.

name (string), required — Pattern: ^[a-z0-9][a-z0-9\-]*$
Name to identify this Zarf package.
annotations (map[string]string)
Annotations are key-value pairs that can be used to store metadata about the package.
architecture (string) — Examples: arm64, amd64
The target cluster architecture for this package.
description (string)
Additional information about this Zarf package.
preventNamespaceOverride (boolean)
Prevent namespace overrides for this package.
uncompressed (boolean)
Disable compression of this package.
version (string)
Generic string set by a package author to track the package version.

Values

Values defines values files and schema for templating and overriding Helm values.

files ([]string)
List of values file paths to include.
schema (string)
Path to a JSON schema file for validating values.

Differential

Differential identifies the base package used to create a differential package.

fromVersion (string), required
Version of a previously built package used as the basis for creating this differential package.

VersionRequirement

VersionRequirement specifies a minimum Zarf version needed and the reason for the requirement.

reason (string), required
The reason this version is required.
version (string), required
The minimum version of Zarf required.

ComponentActions

ComponentActions are ActionSets that map to different Zarf package operations.

onCreate (ComponentActionSet)
Actions to run during package creation.
onDeploy (ComponentActionSet)
Actions to run during package deployment.
onRemove (ComponentActionSet)
Actions to run during package removal.

Chart

Chart defines a helm chart to be deployed.

name (string), required — Pattern: ^[^/\\]*$
The name of the chart within Zarf; note that this must be unique and does not need to be the same as the name in the chart repository.
git (GitSource)
The Git repository where the chart is stored.
helmRepository (HelmRepositorySource)
The Helm repository where the chart is stored.
local (LocalSource)
The local path where the chart is stored.
namespace (string)
The namespace to deploy the chart to.
oci (OCISource)
The OCI registry where the chart is stored.
releaseName (string)
The name of the Helm release to create (defaults to the Zarf name of the chart).
serverSideApply (string) — One of: "true", "false", "auto"; Default: "auto"
Controls whether Helm uses Server-Side Apply (SSA) or client-side apply (CSA) when deploying this chart. Defaults to "auto" when omitted.
skipSchemaValidation (boolean)
Skip validation of the chart's values against its JSON schema. Defaults to false.
skipWait (boolean)
Whether to skip waiting for chart resources to be ready before continuing.
values ([]ChartValue)
List of value sources mapped to their Helm override targets.
valuesFiles ([]ValuesFile)
List of values files to include in the package; these will be merged together when deployed.

File

File defines a file to deploy.

destination (string), required
The absolute or relative path where the file or folder should be copied to during package deploy.
source (string), required
Local folder or file path or remote URL to pull into the package.
checksum (string)
Optional checksum of the file in the format <algorithm>:<checksum> (e.g. sha256:abc123). Defaults to sha256 if no algorithm is specified.
enableTemplating (boolean)
EnableTemplating enables go-template processing on this file during deploy.
executable (boolean)
Determines if the file should be made executable during package deploy.
extractPath (string)
Local folder or file to be extracted from a 'source' archive.
symlinks ([]string)
List of symlinks to create during package deploy.

ImageArchive

ImageArchive defines a tar archive of images to include in the package.

images ([]ArchiveImage), required
The list of images contained in the archive.
path (string), required
The path to the tar archive.

Image

Image defines an OCI image to include in the package.

name (string), required
The image reference.
id (string)
Optional ID, unique within the component; matching IDs let importing components replace regular images.
source (string) — One of: "registry", "daemon"; Default: "registry"
The source to pull the image from. Defaults to "registry".

ComponentImport

ComponentImport is a reference to imported Zarf component configs.

local ([]ComponentImportLocal)
Local file path references to component config files to import.
remote ([]ComponentImportRemote)
OCI URL references to remote component config files to import; pulled at create time.

Manifest

Manifest defines raw manifests Zarf will deploy as a helm chart.

name (string), required — Pattern: ^[^/\\]*$
A name to give this collection of manifests; this will become the name of the dynamically-created helm chart.
enableTemplating (boolean)
EnableTemplating enables go-template processing on these manifests during deploy.
files ([]string)
List of local K8s YAML files or remote URLs to deploy (in order).
kustomize (KustomizeManifest)
Kustomize settings for this manifest.
namespace (string)
The namespace to deploy the manifests to.
serverSideApply (string) — One of: "true", "false", "auto"; Default: "auto"
Controls whether Server-Side Apply (SSA) or client-side apply (CSA) is used during deploy. Defaults to "auto" when omitted.
skipWait (boolean)
Whether to skip waiting for manifest resources to be ready before continuing.

Repository

Repository defines a git repository to include in the package.

url (string), required
The URL of the git repository.
ref (GitRef)
The Git reference to mirror. Optional; when unset, all branches and tags are mirrored.

ComponentSelector

ComponentSelector filters a component for inclusion at package create time.

architecture (string) — One of: "amd64", "arm64"
Only include component for the given package architecture.
flavor (string)
Only include this component when a matching '--flavor' is specified on 'zarf package create'.

Service

Service identifies which Zarf CLI service a component provides.

name (string), required — One of: "registry", "seed-registry", "injector", "agent", "git-server"
The name of the Zarf CLI service this component provides.

ComponentTarget

ComponentTarget filters a component to only apply for a given local OS at deploy time.

os (string) — One of: "linux", "darwin", "windows"
Only deploy component to specified OS.

ComponentActionSet

ComponentActionSet is a set of actions to run during a Zarf package operation.

before ([]ComponentAction)
Actions to run at the start of an operation.
defaults (ComponentActionDefaults)
Default configuration for all actions in this set.
onFailure ([]ComponentAction)
Actions to run if any operation in this set fails.
onSuccess ([]ComponentAction)
Actions to run at the end of an operation if it succeeds.

GitSource

GitSource represents a Helm chart stored in a Git repository.

path (string)
The subdirectory containing the chart within a Git repo.
ref (GitRef)
The Git reference to check out. Required for charts.
url (string)
The URL of the Git repository where the Helm chart is stored. Must not contain an @ref suffix.

HelmRepositorySource

HelmRepositorySource represents a Helm chart stored in a Helm repository.

name (string)
The name of a chart within a Helm repository.
url (string)
The URL of the chart repository where the Helm chart is stored.
version (string)
The version of the chart in the Helm repository.

LocalSource

LocalSource represents a Helm chart stored locally.

path (string), required
The path to a local chart's folder or .tgz archive.

OCISource

OCISource represents a Helm chart stored in an OCI registry.

ref (OCIRef)
The OCI reference to pull. Exactly one of Ref.Tag or Ref.Digest must be set.
url (string)
The URL of the OCI registry where the Helm chart is stored.

ChartValue

ChartValue maps a values source path to a Helm chart target path.

sourcePath (string), required
The source path for the value.
targetPath (string), required
The target path within the Helm chart values.
excludePaths ([]string)
Paths under sourcePath to omit when mapping to the target. Each path must be a descendant of sourcePath.

ValuesFile

ValuesFile is a values file merged into a Helm chart on deploy.

path (string), required
Local path or remote URL of the values file.
enableTemplating (boolean)
Render Zarf template values in the file at deploy time before merging it.

ArchiveImage

ArchiveImage identifies an image selected from an archive.

name (string), required
The image reference contained in the archive.
id (string)
Optional ID, unique across regular and archive images in the component. Does not enable import overrides.

ComponentImportLocal

ComponentImportLocal is a local file path reference to a component config.

path (string), required
The local file path to the component config.

ComponentImportRemote

ComponentImportRemote is a remote OCI URL reference to a component config.

url (string), required
The OCI URL of the remote component config.

KustomizeManifest

KustomizeManifest defines kustomization settings for a manifest.

allowAnyDirectory (boolean)
Allow traversing directory above the current directory if needed for kustomization.
enablePlugins (boolean)
Allow external Kustomize plugins when building manifests.
files ([]string)
List of local kustomization paths or remote URLs to include in the package.

GitRef

GitRef selects a single Git reference.

branch (string)
The Git branch.
commit (string) — Pattern: ^[0-9A-Fa-f]{40}$
The Git commit SHA-1.
tag (string)
The Git tag.

ComponentAction

ComponentAction represents a single action to run during a Zarf package operation.

cmd (string)
The command to run. Must specify either cmd or wait for the action to do anything.
description (string)
Description of the action to be displayed during package execution instead of the command.
dir (string)
The working directory to run the command in (default is CWD).
enableTemplating (boolean)
EnableTemplating enables go-template processing on the cmd field.
env ([]string)
Additional environment variables to set for the command.
maxTotalSeconds (integer)
Timeout in seconds for the command (default 0, no timeout for cmd actions and 300, 5 minutes for wait actions).
retries (integer)
Retry the command if it fails up to a given number of times (default 0).
setValues ([]SetValue)
An array of values to set with the output of the command.
shell (Shell)
Indicates a preference for a shell for the provided cmd.
silent (boolean)
Hide the output of the command during package deployment (default false).
wait (ComponentActionWait)
Wait for a condition to be met before continuing.

ComponentActionDefaults

ComponentActionDefaults sets the default configs for child actions.

dir (string)
Working directory for commands (default CWD).
env ([]string)
Additional environment variables for commands.
maxTotalSeconds (integer)
Default timeout in seconds for commands (default 0, no timeout).
retries (integer)
Retry commands a given number of times if they fail (default 0).
shell (Shell)
Indicates a preference for a shell for the provided cmd to be executed in on supported operating systems.
silent (boolean)
Hide the output of commands during execution (default false).

OCIRef

OCIRef selects a single OCI reference.

digest (string)
The OCI digest, in the form sha256:<sha>.
tag (string)
The OCI tag.

SetValue

SetValue declares a value that can be set during a package deploy.

key (string)
Key represents which value to assign to.
type (string) — One of: "yaml", "json", "string"; Default: "string"
Type declares the kind of data being stored in the value. Defaults to "string" when omitted.

Shell

Shell represents the desired shell to use for a given command.

darwin (string) — Examples: sh, bash, zsh
Darwin (macOS) shell preference.
linux (string) — Examples: sh, bash, zsh
Linux shell preference.
windows (string) — Examples: powershell, cmd, pwsh
Windows shell preference.

ComponentActionWait

ComponentActionWait specifies a condition to wait for before continuing.

cluster (ComponentActionWaitCluster)
Wait for a condition to be met in the cluster before continuing. Only one of cluster or network can be specified.
network (ComponentActionWaitNetwork)
Wait for a condition to be met on the network before continuing. Only one of cluster or network can be specified.

ComponentActionWaitCluster

ComponentActionWaitCluster specifies a cluster-level condition to wait for.

kind (string), required — Examples: Pod, Deployment
The kind of resource to wait for.
name (string), required — Examples: podinfo, app=podinfo
The name of the resource or selector to wait for.
condition (string) — Examples: Available
The condition or jsonpath state to wait for; defaults to kstatus readiness checks.
namespace (string)
The namespace of the resource to wait for.

ComponentActionWaitNetwork

ComponentActionWaitNetwork specifies a network-level condition to wait for.

address (string), required — Examples: localhost:8080, 1.1.1.1
The address to wait for.
protocol (string), required — One of: "tcp", "http", "https"
The protocol to wait for.
code (integer) — Examples: 200, 404
The HTTP status code to wait for if using http or https.