Skip to main content

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

%3CmxGraphModel%3E%3Croot%3E%3CmxCell%20id%3D%220%22%2F%3E%3CmxCell%20id%3D%221%22%20parent%3D%220%22%2F%3E%3CmxCell%20id%3D%222%22%20value%3D%22%22%20style%3D%22rounded%3D1%3BwhiteSpace%3Dwrap%3Bhtml%3D1%3BlabelBorderColor%3Dnone%3BfillColor%3D%23bac8d3%3BstrokeColor%3D%2323445d%3BgradientColor%3Dnone%3Bglass%3D0%3Bshadow%3D0%3Bsketch%3D0%3B%22%20vertex%3D%221%22%20parent%3D%221%22%3E%3CmxGeometry%20x%3D%22210%22%20y%3D%22-60%22%20width%3D%22770%22%20height%3D%22908%22%20as%3D%22geometry%22%2F%3E%3C%2FmxCell%3E%3C%2Froot%3E%3C%2FmxGraphModel%3E
%3CmxGraphModel%3E%3Croot%3...
%3CmxGraphModel%3E%3Croot%3E%3CmxCell%20id%3D%220%22%2F%3E%3CmxCell%20id%3D%221%22%20parent%3D%220%22%2F%3E%3CmxCell%20id%3D%222%22%20value%3D%22%22%20style%3D%22rounded%3D1%3BwhiteSpace%3Dwrap%3Bhtml%3D1%3BlabelBorderColor%3Dnone%3BfillColor%3D%23bac8d3%3BstrokeColor%3D%2323445d%3BgradientColor%3Dnone%3Bglass%3D0%3Bshadow%3D0%3Bsketch%3D0%3B%22%20vertex%3D%221%22%20parent%3D%221%22%3E%3CmxGeometry%20x%3D%22210%22%20y%3D%22-60%22%20width%3D%22770%22%20height%3D%22908%22%20as%3D%22geometry%22%2F%3E%3C%2FmxCell%3E%3C%2Froot%3E%3C%2FmxGraphModel%3E
%3CmxGraphModel%3E%3Croot%3...
%3CmxGraphModel%3E%3Croot%3E%3CmxCell%20id%3D%220%22%2F%3E%3CmxCell%20id%3D%221%22%20parent%3D%220%22%2F%3E%3CmxCell%20id%3D%222%22%20value%3D%22%22%20style%3D%22rounded%3D1%3BwhiteSpace%3Dwrap%3Bhtml%3D1%3BlabelBorderColor%3Dnone%3BfillColor%3D%23bac8d3%3BstrokeColor%3D%2323445d%3BgradientColor%3Dnone%3Bglass%3D0%3Bshadow%3D0%3Bsketch%3D0%3B%22%20vertex%3D%221%22%20parent%3D%221%22%3E%3CmxGeometry%20x%3D%22210%22%20y%3D%22-60%22%20width%3D%22770%22%20height%3D%22908%22%20as%3D%22geometry%22%2F%3E%3C%2FmxCell%3E%3C%2Froot%3E%3C%2FmxGraphModel%3E
%3CmxGraphModel%3E%3Croot%3...
ns
ns
ns
ns
pod
pod
rs
rs
deploy
deploy
Zarf-Managed Deployments
Zarf-Managed Deployments
ns
ns
%3CmxGraphModel%3E%3Croot%3E%3CmxCell%20id%3D%220%22%2F%3E%3CmxCell%20id%3D%221%22%20parent%3D%220%22%2F%3E%3CmxCell%20id%3D%222%22%20value%3D%22%22%20style%3D%22rounded%3D1%3BwhiteSpace%3Dwrap%3Bhtml%3D1%3BlabelBorderColor%3Dnone%3BfillColor%3D%23bac8d3%3BstrokeColor%3D%2323445d%3BgradientColor%3Dnone%3Bglass%3D0%3Bshadow%3D0%3Bsketch%3D0%3B%22%20vertex%3D%221%22%20parent%3D%221%22%3E%3CmxGeometry%20x%3D%22210%22%20y%3D%22-60%22%20width%3D%22770%22%20height%3D%22908%22%20as%3D%22geometry%22%2F%3E%3C%2FmxCell%3E%3C%2Froot%3E%3C%2FmxGraphModel%3E
%3CmxGraphModel%3E%3Croot%3E%3CmxCell%20id%3D%220%22%2F%3E%3CmxCell%20id%3D%221%22%20parent%3D%220%22%2F%3E%3CmxCell%20id%3D%222...
pod
pod
pvc
pvc
nodeport
svc
nodeport...
rs
rs
deploy
deploy
Zarf Registry
Zarf Registry 
clusterip
svc
clusteri...
rs
rs
deploy
deploy
Zarf Agent
(Mutating Webhook)
Zarf Agent...
pod
pod
pvc
pvc
clusterip
svc
clusteri...
rs
rs
deploy
deploy
Zarf Gitops Service
Zarf Gitops Service
pod
pod
ns
ns
zarf-state
zarf-sta...
NodePort
31999
NodePort...
zarf
zarf
pv
pv
sc
sc
nodeport
svc
nodeport...
Zarf Injector
Zarf Injector
pod
from existing
image
pod...
Dynamic configmaps:
n = tarball size / 512 KB
Dynamic configmaps:...
Dynamic
NodePort

Dynamic...
pv
pv
sc
sc
Zarf Resource
Zarf Resource
Zarf Temporary Resource
Zarf Temporary Resource
Zarf-Managed Resource
Zarf-Managed Resource
Zarf CLI to Cluster Comms
Zarf CLI to Cluster Comms
Image Pull From Zarf Registry
Image Pull From Zarf Registry
Standard K8s Comms
Standard K8s Comms
Standard K8s Controller Comms
Standard K8s Controller Comms
Initial image pulled from zarf-injector nodeport
Initial image pulled from zarf-injector nodep...
Post registry boot all images pull from the registry
Post registry boot all images pull from the regi...
POD Create / Flux GitRepository Create Webhook
POD Create / Flux GitRepository Create Webhook
https://github.com/defenseunicorns/zarf
https://github.com/defenseunicorns/zarf
1. Create the Zarf State in the cluster
1. Create the Zarf State in the clu...
2. Launch the injector system
   2. Launch the injector system
3. Deploy the Zarf Registry
   3. Deploy the Zarf Registry
4. Deploy the Zarf Agent
   4. Deploy the Zarf Agent
5. (Optional) Deploy the Zarf Git Server
5. (Optional) Deploy the Zarf Git S...
6. Push package assets to the cluster
6. Push package assets to the clust...
Text is not SVG - cannot display