Backends

​

At a glance

​

Choosing a backend

• You run many short-lived sandboxes per node and want the smallest possible footprint.
• You don’t need to pause, resume, fork, or persist state between restarts.
• You’re on a single node and don’t need replication.
• Security is paramount: Firecracker has the smallest attack surface, and the jailer is active (verified by tests/integration/test_firecracker.py::test_jailer_active).

• You need a real persistent disk that survives pod restarts (/mnt/state mount inside the sandbox).
• You want to pause / resume / fork sandboxes at the disk level.
• You run multi-node and want data to survive node failure (Longhorn replicates).
• You need bigger root disks (sized with --root-disk-size).

• Fork latency matters: k7d warm-forks a running VM in ~5 ms with faithful memory, disk, process, and network state — versus ~45 s for a disk-only Longhorn fork.
• You want snapshot trees: fork many branches from a checkpoint, protect winners, prune losers, under RAM/disk budgets.
• Your workload is RL training or agent tree search over many resettable environments.

​

Specifying the backend

​

At install time

k7 install                                     # default: kata backends on localhost
k7 install --backend kfd                       # kata-firecracker-devmapper only (auto-detects raw disk)
k7 install --backend kfd --disk /dev/nvme2n1   # pin the thin-pool disk explicitly
k7 install --backend kql                       # kata-qemu-longhorn only, no raw disk needed
k7 install --backend kql --longhorn-extra-disk /mnt/longhorn-extra   # optional extra storage
k7 install --backend k7d                       # k7d runtime (daemon + shim + RuntimeClass k7)
k7 install --backend k7d --k7d-version 0.1.0   # pin the k7d release to download
k7 install --backend k7d --k7d-artifact /root/k7d-v0.1.0-x86_64-linux.tar.gz   # install from a local tarball
k7 install --backend kfd,kql --disk /dev/nvme2n1 --longhorn-extra-disk /mnt/longhorn-extra   # multiple, explicit
k7 install -i inventory.ini                    # multi-node, per-host backends
k7 install -i inventory.ini --ha               # multi-master HA (3+ servers, embedded etcd)

​

At sandbox creation time

# Auto-detect (uses the only backend installed, or falls back to kfd if several)
k7 create --image alpine:3.20 demo

# Explicit
k7 create --backend kql --image alpine:3.20 demo
k7 create --backend k7d --image alpine:3.20 demo

# In YAML
# k7.yaml:
backend: kata-qemu-longhorn   # or kata-firecracker-devmapper, k7d — or alias kql / kfd

​

Backend-specific behavior

​

kata-qemu-longhorn

• Each sandbox gets a Longhorn PVC named <sandbox>-root-lh, defaulting to 10Gi (override with --root-disk-size 20Gi or in YAML).
• The container runs privileged to allow the persistence wrapper to bind-mount /mnt/state from the PVC.
• Image base must include /bin/sh, tar, and mount (Debian/Ubuntu/Alpine all work).
• Image ENTRYPOINT+CMD are preserved by default — override with --entrypoint / --cmd.
• pause takes a crash-consistent VolumeSnapshot before scaling to 0 (optional; pass --snapshot <name>).
• fork snapshots the source PVC, clones it via Longhorn’s CSI VolumeSnapshot+Restore, then creates a new Deployment pointing at the cloned PVC.

​

kata-firecracker-devmapper

• Sandbox storage is a per-pod logical volume on the LVM thin-pool — fast to create, lost on delete.
• The Firecracker process runs inside the jailer: a chroot, with dropped capabilities and a restrictive seccomp filter, as an unprivileged UID.
• No pause/resume/fork — there’s no persistent disk to snapshot.
• --root-disk-size has no effect (warned by the CLI).

​

k7d

• Pods run as k7d microVMs via runtimeClassName: k7 — a small containerd shim talks to the k7d daemon over /run/k7d/k7d.sock.
• Fork copies the whole VM: memory, disk, processes, and network identity — not just the disk. Warm fork is ~5 ms.
• Multi-vCPU guests are supported: the vCPU count is derived from the pod’s CPU limit (cpu: "2" boots a 2-vCPU guest), with fork/snapshot parity.
• VM ops work for sandboxes on any node. The k7d daemon and its socket are node-local, but k7 pause / resume / fork through the API are forwarded to the k7-agent DaemonSet pod on the sandbox’s node when needed. A fork still lands on the source’s node (cross-node fork is on the k7d roadmap).
• Warm fork works for single-workload sandboxes; forking a sandbox with a sidecar is rejected (use kql for that).
• Per-node k7d disk-pool utilization is visible via k7 nodes storage (see CLI reference).
• See RuntimeClass k7 for how the runtime is registered, and the feature matrix for current Kubernetes feature support.