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
• Until #306 is merged, during helm install/upgrade a Helm PostRender function is called to mutate images and ImagePullSecrets so the deployed resources use the NodePort binding
• 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