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.
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”.
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.
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. To install a K8s distribution other than K3s, finding or creating a custom Zarf Package is necessary.
Typically, an init package is the first Zarf Package to be deployed on a cluster as other packages often rely on the services it installs or configures, however Zarf may be used to package and install the cluster distribution itself. In this scenario, the distribution package would be deployed first, followed by the init package, and then any other packages planned for deployment.
During the initialization process, Zarf will seed the cluster with a container registry to store images that other packages may require. 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. For additional information on the init package, we provide detailed documentation on the Zarf ‘init’ package page.
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 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.
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.
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:
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
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.
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.
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.