Creating a Custom 'init' Package

Introduction

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.

System Requirements

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

Prerequisites

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
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

tip

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.

note

Prior to v0.26.0 AGENT_IMAGE_TAG was 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 y or n.

tip

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 0.

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.

Swapping Images

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.

tip

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

Removing Components

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.

Troubleshooting

Unable to read zarf.yaml file

Remediation

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.