Creating a Custom 'init' Package

In most cases the default Zarf ‘init’ Package will provide what you need to get started deploying packages into the air gap, however there are cases where you may want to tweak this package to tailor it for your target environment. This could include adding or removing components or including hardened versions of components specific to your use case.

In this tutorial, we will demonstrate how to build a custom Zarf ‘init’ Package with zarf package create.

When creating a Zarf ‘init’ package, you must have a network connection so that Zarf can fetch all of the dependencies and resources necessary to build the package. If your version of the ‘init’ package is using images from a private registry or is referencing repositories in a private repository, you will need to have your credentials configured on your machine for Zarf to be able to fetch the resources.

For the default init package you will require an Internet connection to pull down the resources Zarf needs.

Before beginning this tutorial you will need the following:

The Zarf repository cloned: (git clone instructions)
Zarf binary installed on your $PATH: (Installing Zarf)
(if building a local zarf-agent) The Docker CLI installed and the tools to Build your own CLI

Creating the zarf ‘init’ package is as simple as creating any other package. All you need to do is run the zarf package create command within the Zarf git repository.

$ cd zarf # Enter the zarf repository that you have cloned down
$ zarf version
vX.X.X
$ git checkout vX.X.X # checkout the version that corresponds to your zarf version
# Run the command to create the zarf package where the AGENT_IMAGE_TAG matches your zarf version
$ zarf package create . --set AGENT_IMAGE_TAG=vX.X.X
# Type `y` when prompted and then hit the enter key

When you execute the zarf package create command, Zarf will prompt you to confirm that you want to create the package by displaying the package definition and asking you to respond with either y or n.

After you confirm package creation, Zarf will create the Zarf ‘init’ package in the current directory. In this case, the package name should look something like zarf-init-amd64-vX.X.X.tar.zst, although it might differ slightly depending on your system architecture.

The above will simply build the init package as it is defined for your version of Zarf. To build something custom you will need to make some modifications.

The Zarf ‘init’ Package is a composed Zarf Package made up of many sub-Zarf Packages. The root zarf.yaml file is defined at the root of the Zarf git repository.

As of v0.26.0 you can swap the registry and agent images by specifying different values in the zarf-config.toml file at the root of the project or by overriding them as we did above with --set on the command line. This allows you to swap these images for hardened or enterprise-vetted versions like those from Iron Bank.

For other components, or older versions of Zarf, you can modify the manifests of the components you want to change in their individual packages under the packages folder of the Zarf repo.

If your enterprise uses pull-through mirrors to host vetted images you can run the following command to create a Zarf ‘init’ package from those mirrors (where <registry>.enterprise.corp are your enterprise mirror(s)):

$ zarf package create . --set AGENT_IMAGE_TAG=vX.X.X \
  --registry-override docker.io=dockerio.enterprise.corp \
  --registry-override ghcr.io=ghcr.enterprise.corp \
  --registry-override quay.io=quay.enterprise.corp

And if you need even more control over the exact Agent, Registry, and Gitea images you can specify that with additional --set flags:

$ zarf package create . \
--set AGENT_IMAGE_TAG=$(zarf version) \
--set AGENT_IMAGE="opensource/zarf" \
--set AGENT_IMAGE_DOMAIN="custom.enterprise.corp" \
--set REGISTRY_IMAGE_TAG=2.8.3 \
--set REGISTRY_IMAGE="opensource/registry" \
--set REGISTRY_IMAGE_DOMAIN="custom.enterprise.corp" \
--set GITEA_IMAGE="custom.enterprise.corp/opensource/gitea:v1.21.0-rootless"

⚠️ - The Gitea image is different from the Agent and Registry in that Zarf will always prefer the rootless version of a given server image. The image no longer must be tagged with -rootless, but it still needs to implement the Gitea configuration of a rootless image. If you need to change this, edit the packages/gitea package.

You can find all of the --set configurations by looking at the zarf-config.toml in the root of the repository.

You may not need or want all of the components in your ‘init’ package and may choose to slim down your package by removing them. Because the Zarf Package is composed all you need to do is remove the component that imports the component you wish to exclude.