Package Components

danger

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

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 and Remote

Remote with SHA sums

Helm Charts

Can be when using the localPath key:

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

Can be when using the url key:

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

Chart Examples

localPath

URL (git)

URL (oci)

Kubernetes Manifests

Can be when using the files key:

• 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)

Can be when using the kustomizations key:

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

Manifest Examples

Local

info

While this explanation does not showcase it, you can also specify a local directory containing a kustomization.yaml file and Zarf will automatically run kustomize build on the directory during zarf package create, rendering the Kustomization into a single manifest file.

Remote

Container Images

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

note

zarf prepare find-images has some known limitations due to the numerous ways images can be defined in Kubernetes resources, but should work for most standard manifests, kustomizations, and helm charts.

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

Path

OCI

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