VM Images¶
Tenant worker nodes are KubeVirt VMs, so every tenant cluster needs a worker disk image. kMetal supports two boot modes and a golden-image pipeline for producing them.
Boot modes¶
ContainerDisk — ephemeral, fast first boot¶
A ContainerDisk is a KubeVirt boot mode where the OS image is shipped as a container image. The VM mounts the image from the container registry at boot time and runs against a writable overlay; the underlying image is read-only and shared across worker VMs.
- First-boot time: ~50 seconds.
- Persistence: ephemeral. The overlay is discarded when the VM is destroyed.
- Best for: production worker nodes that are routinely rebuilt, where the cluster expects worker churn (e.g., the autoscaler creates and tears down workers). No state survives a VM rebuild, which matches what kubeadm-managed workers want anyway.
- Used by: the
kubevirt-kubeadmClusterClass tier (Ubuntu ContainerDisk + kubeadm bootstrap, the default production tier).
DataVolume — persistent, snapshot-cloned¶
A DataVolume is a KubeVirt boot mode where the disk is a PersistentVolume cloned from a snapshot of a golden image. The VM writes to its own copy; the snapshot is unchanged.
- First-boot time: ~3–4 minutes (clone happens on first boot). Subsequent restarts are fast (the disk already exists).
- Persistence: yes. The VM's disk survives shutdown / restart; deleting the VM deletes the disk.
- Best for: tenant workloads that benefit from a fast image with the entire kubelet, container runtime, and add-ons pre-installed in the disk (Kairos golden image). Long-running worker pools where a 3-minute one-time cost amortizes well.
- Used by: additional Kairos-based ClusterClass tiers, when present in your environment.
The boot mode is part of the ClusterClass; tenants pick a tier, the tier picks the mode. Operators don't configure boot mode per cluster — they pick the ClusterClass tier per cluster.
Golden-image pipeline¶
The persistent DataVolume mode needs an image to clone from. kMetal builds those images in-cluster via the image-builder Helm chart on the under cluster.
The pipeline is:
- OSArtifact CR. Defines what to build (Kairos base, Kubernetes version, kernel parameters, baked-in add-ons).
- Builder Job. Runs in the under cluster; produces a raw disk image.
- Installer VM. Boots the disk image once, performs first-boot setup (cloud-init bake-in, container-runtime warm-up), and shuts down.
- VolumeSnapshot. Snapshots the resulting disk.
- Golden DataVolume. A PVC pre-populated from the snapshot; subsequent tenant worker VMs clone from this DataVolume.
The whole flow runs inside the under cluster — no external image-builder service, no manual upload, no out-of-band image registry. Operators can rebuild the golden image at will (kernel CVE, Kubernetes version bump, add-on update), and the next time a tenant cluster's MachineDeployment scales up, the new workers come up on the new image.
Worked examples for different storage backends are t.b.d. in this section.
Picking a boot mode¶
| Concern | ContainerDisk | DataVolume |
|---|---|---|
| First-boot time | ~50 s | ~3–4 min |
| Restart time (existing VM) | ~50 s (re-clone from image) | seconds |
| Persistence | Ephemeral | Persistent |
| Storage cost | Negligible (shared read-only) | One PVC per VM |
| Best fit | High-churn worker pools | Long-lived workers, baked-in add-ons |
| ClusterClass tier | kubevirt-kubeadm (default) |
Kairos-based tiers (when present) |
When in doubt, start with kubevirt-kubeadm (ContainerDisk). The Kairos tiers are the right pick when you need a more comprehensive image (e.g., add-ons pre-installed for an air-gapped tenant, or a specific kernel build).