Skip to content

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:

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.

Terminal window
$ 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

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.

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.