From ba8ecf1d603fdb71e8062373180c1e7d5d4e9afc Mon Sep 17 00:00:00 2001 From: Wayland Yang Date: Sun, 14 Jun 2026 02:50:04 +0800 Subject: [PATCH] =?UTF-8?q?docs(readme):=20add=20guest/host=20kernel=20sup?= =?UTF-8?q?port=20matrix=20=E2=80=94=20closes=20#244?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit @hty993 (#244) flagged that there's no documented "supported kernel versions" story, which is a real gap for fleet deployment. Adding a matrix to the Enterprise deployment FAQ. The key clarification the issue was missing: there are *two* kernels, and only the host is the user's variable. - Guest kernel: forkd ships and pins vmlinux-6.1.141. Every snapshot is taken and restored against the same guest kernel, so it's constant across all hosts — it is never the reason a snapshot won't restore elsewhere. - Host kernel: ≥5.7 for live BRANCH (UFFDIO_WRITEPROTECT on memfd), any KVM-capable kernel for basic fork / Diff BRANCH. Tested on 6.14. Deliberately did NOT reproduce the issue's proposed per-version table (6.6.x / 6.8.x "restore broken on 6.8.0-6.8.4" / 6.11.x) — none of those claims are sourceable in this repo or attributed upstream, and a wrong authoritative-looking matrix is worse for fleet operators than a pointer to Firecracker's own kernel-support policy (which owns the host-kernel ABI question and won't drift against a copy here). Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/README.md b/README.md index d6c467e..0f4f59c 100644 --- a/README.md +++ b/README.md @@ -423,6 +423,15 @@ Measured CoW overhead at N=100 is **0.12 MiB / child** on top of the parent ([be - **Untrusted CI** — `git clone + pip install + pytest` inside a real Linux VM, not a container namespace - **Fork-per-test isolated databases** — recipe: [`postgres-fixture/`](./recipes/postgres-fixture/) — ready-to-query postgres at ~10 ms per child instead of ~2 s of fresh `initdb` +**Which kernels does forkd run on?** Two kernels are in play, and only one is yours to worry about: + +| Kernel | Who picks it | Version | Notes | +|---|---|---|---| +| **Guest** (boots inside each microVM) | forkd ships it | `vmlinux-6.1.141` (fixed) | Firecracker's CI-blessed image; every snapshot is taken *and* restored against this same guest kernel, so the guest side is identical on every host. `scripts/install-guest-kernel.sh` installs it; `forkd doctor` verifies it. | +| **Host** (runs Firecracker + KVM) | your machine | **≥ 5.7 for live BRANCH**, any KVM-capable kernel otherwise | Live (`--live`) BRANCH needs `UFFDIO_WRITEPROTECT` on memfd (Linux 5.7+, `forkd doctor` probes it). Basic fork / Diff BRANCH work on older KVM kernels. Tested on 6.14 (CI + dev box); the K8s example targets 6.14. | + +The host kernel is where Firecracker's own version sensitivity lives (KVM ABI, snapshot compatibility) — see [Firecracker's kernel support policy](https://github.com/firecracker-microvm/firecracker/blob/main/docs/kernel-policy.md) for the authoritative host-kernel matrix rather than a copy that can drift. Snapshots are **not** portable across *Firecracker* versions or host CPU microarchitectures (a separate concern from kernel version); `forkd doctor` reports both your FC version and guest kernel so a fleet can assert they match. +
## Quick start