Package Components
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)
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
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
.
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
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