Updating docs

2026-06-13 05:06:44 +00:00
parent b27913a7c9
commit 8f7833a7e0
3 changed files with 133 additions and 0 deletions
@@ -0,0 +1,60 @@
+# Design v2 — implementation errata (RHEL/Rocky 9)
+
+Records where the as-built implementation diverges from
+`diskless-fleet-design-v2.pdf`. The PDF remains authoritative for the
+architecture; this note captures deltas discovered bringing the build up on
+**Rocky 9.8** until they are folded into a consolidated **v3**. Last updated
+2026-06-13.
+
+The architecture is unchanged: 802.1X EAP-TLS with a TPM-held key, MACsec on the
+access link, dm-verity-protected erofs root over NVMe/TCP, signed UKI, and the
+FROM-scratch OCI release artifact. Only the items below differ.
+
+## 1. Design-level change — writable root overlay
+
+**PDF says (§3 step 8, §5):** runtime state lives on a tmpfs overlay enabled by
+the kernel cmdline option **`rootovl`**.
+
+**As built:** the cmdline uses **`systemd.volatile=overlay`** instead.
+
+**Why:** `rootovl`/`overlayfs` is a Debian/third-party dracut module; RHEL/Rocky
+dracut does not ship it (`dracut: module 'overlayfs' cannot be found`).
+`systemd.volatile=overlay` is the RHEL-native, systemd-supported mechanism and
+is the recommended overlay for dm-verity-protected read-only roots. Behaviour is
+equivalent: the verity erofs root mounts read-only and a tmpfs overlay carries
+runtime writes; per-host `machine-id` is still generated into the overlay.
+
+**Caveat:** requires `systemd-volatile-root.service` in the initramfs (bundled by
+recent dracut; `install_items` it if the root stays read-only at boot). The known
+failure mode is NFS root — not applicable here (NVMe block root). Set in
+[../scripts/extract-artifacts.sh](../scripts/extract-artifacts.sh); module list
+in [../files/etc/dracut.conf.d/90-diskless.conf](../files/etc/dracut.conf.d/90-diskless.conf).
+
+## 2. Implementation notes (not architectural)
+
+These don't contradict the PDF (it doesn't specify them) but are worth recording.
+
+- **Network backend.** The dracut hook uses `network-legacy`/`ifup`, which needs
+  `dhclient`; RHEL 9 deprecated it and the minimal ISO omits it, so the
+  provisioner installs `dhcp-client` explicitly. dhclient is on its way out — the
+  durable fix is porting the hook to the `network-manager` dracut module
+  (tracked; see project todo).
+- **Build ISO.** Defaults to a version-pinned Rocky 9.x **minimal** ISO on the
+  internal mirror (`iso_url` + `sha256` `iso_checksum`). `http/ks.cfg` installs
+  only core+sshd+chrony from the ISO; the diskless tooling is pulled online by
+  the provisioner, so the build VM needs outbound repo access.
+- **Reference serving stack.** §7's SPDK + nginx + DHCP/DNS serving stack has a
+  concrete docker-compose implementation in [../serving/](../serving/), incl.
+  Docker image-volume mounting of the OCI artifact image.
+- Assorted build-time fixes (HCL `%%{` escaping, file-provisioner staging,
+  dracut module naming) are documented in
+  [../CLAUDE.md](../CLAUDE.md) → "RHEL 9.x build notes".
+
+## 3. Temporary deviation — must be reverted before production
+
+- **802.1X/MACsec test bypass.** `disable_dot1x=true` bakes `rd.dot1x=0` into the
+  cmdline so the host skips authentication/MACsec and DHCPs the NIC directly, to
+  validate the UKI/rootfs/NVMe-oF path on an open switch port. The auth stack
+  stays in the image (dormant). This is **lab-only**; a production build must
+  drop the flag (`DISABLE_DOT1X: "false"` in CI) to restore the secure boot
+  chain described throughout the PDF.