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
initpackage 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
Building the init-package
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
$ 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
For development if you omit the
AGENT_IMAGE_TAG Zarf will build a Zarf Agent image based on the source code within the Zarf git repository you cloned.
Prior to v0.26.0
AGENT_IMAGE and would be set like:
zarf package create . --set AGENT_IMAGE=agent:vX.X.X
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
You can skip this confirmation by adding the
--confirm flag when running the command. This will look like:
zarf package create . --confirm
After you confirm package creation, you have the option to specify a maximum file size for the package. To disable this feature, enter
Once you enter your response for the package size, 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.
Customizing the 'init' Package
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
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 \
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.
Unable to read zarf.yaml file
If you receive this error, you may not be in the correct directory. Double-check where you are in your system and try again once you're in the correct directory with the zarf.yaml file that you're trying to build.