Package Components

note

The following examples are not all-inclusive and are only meant to showcase the different types of resources that can be defined in a component. For a full list of fields and their options, please see the component schema documentation.

Overview

The actual capabilities that Zarf Packages provided are defined within named components.

These components define what dependencies they have along with a declarative definition of how they should be deployed.

Each package can have as many components as the package creator wants but a package isn't anything without at least one component.

Fully defined examples of components can be found in the examples section of the documentation.

Common Component Fields

There are certain fields that will be common across all component definitions. These fields are:

Actions

Component actions are explored in the component actions documentation.

Files

Files can be:

• Relative paths to either a file or directory (from the zarf.yaml file)
• A remote URL (http/https)
• Verified using the shasum field for data integrity (optional and only available for files)

File Examples

Local

Remote with SHA sums

Helm Charts

Charts using the localPath key can be:

• Relative paths to either a file or directory (from the zarf.yaml file)

Charts using the url key can be:

• A remote URL (http/https) to a Git repository
• A remote URL (oci://) to an OCI registry
• A remote URL (http/https) to a Helm repository

Chart Examples

Kubernetes Manifests

Manifests under the files key can be:

• Relative paths to a Kubernetes manifest file (from the zarf.yaml file)
• Verified using the url@shasum syntax for data integrity (optional and only for remote URLs)

Manifests under the kustomizations key can be:

• Any valid Kustomize reference both local and remote (ie. anything you could do a kustomize build on)

note

Zarf dynamically generates a Helm Chart from the named manifest entries that you specify. This means that any given set of files under a manifest entry will be applied according to Helm Chart template and manifest install ordering and not necessarily in the order that files are declared. If ordering is important, consider moving each file into its own manifest entry in the manifests array.

Manifest Examples

Local

Remote

Kustomizations

info

Kustomizations are handled a bit differently than normal manifests in that Zarf will automatically run kustomize build on them during zarf package create, thus rendering the Kustomization into a single manifest file. This prevents needing to grab any remote Kustomization resources during zarf package deploy but also means that any Zarf variables will only apply to the rendered manifest not the kustomize build process.

Container Images

Images can either be discovered manually, or automatically by using zarf prepare find-images.

note

zarf prepare find-images will find images for most standard manifests, kustomizations, and helm charts, however some images cannot be discovered this way as some upstream resources (like operators) may bury image definitions inside. For these images, zarf prepare find-images also offers support for the draft Helm Improvement Proposal 15 which allows chart creators to annotate any hidden images in their charts along with the values conditions that will cause those images to be used.

Image Examples

Git Repositories

The git-data example provides an in-depth explanation of how to include Git repositories in your Zarf package to be pushed to the internal/external Git server.

The podinfo-flux example showcases a simple GitOps workflow using Flux and Zarf.

Repository Examples

Full Mirror

Specific Tag

Specific Branch

Specific Hash

Data Injections

Component Imports

Local Path

OCI URL

note

During composition, Zarf will merge the imported component with the component that is importing it. This means that if the importing component defines a field that the imported component also defines, the value from the importing component will be used and override.

This process will also merge variables and constants defined in the imported component's zarf.yaml with the importing component. The same override rules apply here as well.

Extensions

Deploying Components

When deploying a Zarf package, components are deployed in the order they are defined in the zarf.yaml.

The zarf.yaml configuration for each component also defines whether the component is 'required' or not. 'Required' components are always deployed without any additional user interaction while optional components are printed out in an interactive prompt asking the user if they wish to the deploy the component.

If you already know which components you want to deploy, you can do so without getting prompted by passing the components as a comma-separated list to the --components flag during the deploy command.

# deploy all required components, prompting for optional components and variables
$ zarf package deploy ./path/to/package.tar.zst

# deploy all required components, ignoring optional components and variable prompts
$ zarf package deploy ./path/to/package.tar.zst --confirm

# deploy optional-component-1 and optional-component-2 components whether they are required or not
$ zarf package deploy ./path/to/package.tar.zst --components=optional-component-1,optional-component-2