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
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
- Remote
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.
Container Images
Images can either be discovered manually, or automatically by using zarf prepare find-images
.
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
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