Packages

Zarf offers a comprehensive solution for deploying system software or capabilities while fully disconnected. This is accomplished through the use of a single tarball archive, which includes all necessary components and is defined by a zarf.yaml file.

Zarf packages are created while you are connected to internet or intranet resources defined in a Zarf package configuration. This allows these resources to be pulled and stored within a package archive and be deployed on disconnected systems without requiring a connection to the outside world.

The zarf.yaml file also defines declarative instructions for the deployment of package capabilities, which are automatically executed on package deployment and are represented in code. This ensures reproducibility across different systems without the need for manual configuration.

Zarf packages consist of functional blocks, known as components. Components can be optional, providing greater flexibility in package usage. Further details on components can be found on the Zarf Components page.

Types of Zarf Packages

There are two types of Zarf packages, the ZarfInitConfig and the ZarfPackageConfig, which are distinguished by the kind: field and specified in the zarf.yaml file.

Throughout the rest of the documentation, we will refer to the ZarfInitConfig as an init config package or init package, and to the ZarfPackageConfig as simply a “package”.

ZarfInitConfig

The init package is used to initialize a cluster, making it ready for deployment of other Zarf packages. It must be executed once on each cluster that you want to deploy another package onto, even if multiple clusters share the same host. For additional information on the init package, we provide detailed documentation on the Zarf ‘init’ package page.

If there is no running cluster, the init package can be used to create one. It has a deployable K3s cluster component that can be optionally deployed on your machine. Usually, an init package is the first Zarf Package to be deployed on a cluster as other packages often depend on the services installed or configured by the init package. If you want to install a K8s cluster with Zarf, but you don’t want to use K3s as your cluster, you will need to create or find another Zarf Package that will stand up your cluster before you run the zarf init command.

Note

To clarify, in most cases, the first Zarf Package you deploy onto a cluster should be the init package since other packages often depend on the services it installs onto your cluster. However, if you don’t want to use the K3s distribution included in the init package or if you already have a preferred K8s distribution, you can deploy the distribution package first, followed by the init package, and then any other packages you want. This only applies if you don’t have a K8s cluster yet.

During the initialization process, Zarf will seed your cluster with a container registry to store images that other packages may require. Additionally, the init package has the option to deploy other features to your cluster, such as a Git server to manage your repositories or a PLG logging stack that allows you to monitor the applications running on your cluster.

Using the init-package

To initialize your cluster, you need to run the command zarf init. This command will search for a file with the specific naming convention: zarf-init-{ARCHITECTURE}-{VERSION}.tar.zst. The architecture must match that of the cluster you are deploying to. If you are deploying to a cluster with a different architecture, you will need to specify the name of the architecture you are deploying on with the -a flag. For example, if you are on an arm64 machine but are deploying on an amd64 machine, you will run zarf init -a amd64.

You do not need to create init configs by yourself unless you want to customize how your cluster is installed/configured. For example, if you want to use the init process to install a specifically configured K3s cluster onto your host machine, you can create a specific package to do that before running the init package.

ZarfPackageConfig

ZarfPackageConfig refers to any package that is not an init package and is used to define specific capabilities that you want to deploy onto your initialized cluster.

To deploy a Zarf Package, you can use the command zarf package deploy. This will prompt you to select from all of the files in your current directory that match the name zarf-package-*.tar.zst. Alternatively, if you already know which package you want to deploy, you can simply use the command zarf package deploy {PACKAGE_NAME}.

During the deployment process, Zarf will leverage the infrastructure created during the ‘init’ process (such as the Docker registry and Git server) to push all the necessary images and repositories required for the package to operate.

Differential Packages

If you already have a Zarf package and you want to create an updated package you would normally have to re-create the entire package from scratch, including things that might not have changed. Depending on your workflow, you may want to create a package that only contains the artifacts that have changed since the last time you built your package. This can be achieved by using the --differential flag while running the zarf package create command. You can use this flag to point to an already built package you have locally or to a package that has been previously published to a registry.

Package Sources

A source can be used with the following commands as their first argument:

• zarf package deploy <source>
• zarf package inspect <source>
• zarf package remove <source>
• zarf package publish <source>
• zarf package pull <source>
• zarf package mirror-resources <source>

Zarf currently supports consuming packages from the following sources:

Local Tarball Path (.tar and .tar.zst)

A local tarball is the default output of zarf package create and is a package contained within a tarball with or without Zstandard compression. Compression is determined by a given package’s metadata.uncompressed key within it’s zarf.yaml package definition

Split Tarball Path (.part...)

A split tarball is a local tarball that has been split into multiple parts so that it can fit on smaller media when traveling to a disconnected environment (i.e. on DVDs). These packages are created by specifying a maximum number of megabytes with --max-package-size on zarf package create and if the resulting tarball is larger than that size it will be split into chunks.

Remote Tarball URL (http:// and https:// )

A remote tarball is a Zarf package tarball that is hosted on a web server that is accessible to the current machine. By default Zarf does not provide a mechanism to place a package on a web server, but this is easy to orchestrate with other tooling such as uploading a package to a continuous integration system’s artifact storage or to a repository’s release page.

Remote OCI Reference (oci://)

An OCI package is one that has been published to an OCI compatible registry using zarf package publish or the -o option on zarf package create. These packages live within a given registry and you can learn more about them in our Publish & Deploy Packages w/OCI Tutorial.

Note

In addition to the traditional sources outlined above, there is also a special “Cluster” source available on inspect and remove that allows for referencing a deployed package via its name:

• zarf package inspect <package name>
• zarf package remove <package name>

Additionally, inspecting a package deployed to a cluster will not be able to show the package’s SBOMs, as they are not currently persisted to the cluster.