Zarf Nerd Notes

Hard Hat Area

This page is still being developed. More content will be added soon!

Zarf is written entirely in go, except for a single 868Kb binary for the injector system written in rust, so we can fit it in a configmap. All assets are bundled together into a single zstd tarball on each zarf package create operation. On the air gap / offline side, zarf package deploy extracts the various assets and places them on the filesystem or installs them in the cluster, depending on what the zarf package says to do. Some important ideas behind Zarf:

• All workloads are installed in the cluster via the Helm SDK
• The OCI Registries used are both from Docker
• Currently, the Registry and Git servers are not HA, see #375 and #376 for discussion on this
• To avoid TLS issues, Zarf binds to 127.0.0.1:31999 on each node as a NodePort to allow all nodes to access the pod(s) in the cluster
• Zarf utilizes a mutating admission webhook called the zarf-agent to modify the image property within the PodSpec. The purpose is to redirect it to Zarf's configured registry instead of the the original registry (such as DockerHub, GCR, or Quay). Additionally, the webhook attaches the appropriate ImagePullSecret for the seed registry to the pod. This configuration allows the pod to successfully retrieve the image from the seed registry, even when operating in an air-gapped environment.
• Zarf uses a custom injector system to bootstrap a new cluster. See the PR #329 and ADR for more details on how we came to this solution. The general steps are listed below:
  • Get a list of images in the cluster
  • Attempt to create an ephemeral pod using an image from the list
  • A small rust binary that is compiled using musl to keep the max binary size as minimal as possible
  • The registry:2 image is placed in a tar archive and split into 512 KB chunks; larger sizes tended to cause latency issues on low-resource control planes
  • An init container runs the rust binary to re-assemble and extract the zarf binary and registry image
  • The container then starts and runs the rust binary to host the registry image in an static docker registry
  • After this, the main docker registry chart is deployed, pulls the image from the ephemeral pod, and finally destroys the created configmaps, pod, and service

Zarf Architecture