From a74894c6f649317bbfa885fc59707f472b24bd35 Mon Sep 17 00:00:00 2001 From: didericis Date: Sat, 25 Jul 2026 03:17:24 -0400 Subject: [PATCH] docs(prd-0070): correct the firecracker-split difficulty framing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reevaluated against the actual nft ruleset: the firecracker split's isolation is nearly free, not "the real work." Agent VMs are already dropped except the DNAT'd gateway ports, so re-pointing that single DNAT rule at the gateway VM (dnat to $(gw_guest)) isolates agents from a separate orchestrator VM with zero new agent rules; the only added nft is a mirrored gateway link + one gateway->orchestrator forward rule. The effort is the mechanical second-VM lifecycle, and it's validatable on a Firecracker host. Sharpened the Access bullet accordingly and added a note to Sequencing decoupling the original consolidation's "real work" (the broker shim) from the split, whose difficulty actually runs the other way (docker/macOS do the real work — new control network, dual-homed gateway, the token-only->L3 upgrade; firecracker is nearly free). Co-Authored-By: Claude Opus 4.8 --- docs/prds/0070-per-host-orchestrator.md | 31 +++++++++++++++++++------ 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/docs/prds/0070-per-host-orchestrator.md b/docs/prds/0070-per-host-orchestrator.md index 86aed0c..6c4a094 100644 --- a/docs/prds/0070-per-host-orchestrator.md +++ b/docs/prds/0070-per-host-orchestrator.md @@ -413,13 +413,21 @@ blocks it at L3. **The split is the moment to fix that, not a risk to it:** the control net. macOS mirrors this with a second container network and the orchestrator's pinned control-net IP (no Apple DNS — reuse the `gateway_hosts` `/etc/hosts` mechanism). -- **Firecracker — nearly free.** The nft forward chain already drops - everything a VM sends except the DNAT'd gateway ports, so a *separate* - orchestrator VM is unreachable by agent VMs with **no new agent rules**. The - new piece is a gateway-VM ↔ orchestrator-VM link — the same shape as today's - orch `/31` link, but between the two infra VMs instead of loopback within - one — with a forward-accept rule for that link alone. Agent egress DNATs to - the **gateway** VM's data ports; nothing DNATs to the orchestrator VM. +- **Firecracker — the isolation is nearly free; the work is a second VM.** The + nft forward chain already drops everything an agent VM sends except the + DNAT'd gateway ports, so re-pointing that **single DNAT rule** at the gateway + VM (`dnat to $(gw_guest)` instead of `$(orch_guest)` in + `scripts/firecracker-netpool.sh`) isolates agents from a *separate* + orchestrator VM with **zero new agent rules** — the existing `drop` handles + the rest. The only *added* nft is a second infra link that mirrors today's + orch `/31` block (a `masquerade` for its upstream egress) plus one + `iifname "$GW_IFACE" oifname "$ORCH_IFACE" accept` so the gateway VM reaches + `orch_guest:8099`. The actual effort is the **lifecycle** — a second infra VM + in the pool (boot / adopt / health / teardown, split init scripts) — + mechanical because it mirrors the existing single-VM code. All of it is + validatable on a Firecracker host (inspect the nft table; confirm an agent VM + cannot reach `orch_guest:8099`), so despite the PRD's earlier framing this is + **not** the hard or risky part of the split. Role-scoped JWT auth (#469) stays as defense-in-depth on all three, unchanged. A *compromised gateway* can already reach the orchestrator today @@ -496,6 +504,15 @@ Backend order (cheapest proof → hardest → last): the dev-harness so the app logic is already proven. 3. **macOS (Apple container)** — last (container-to-container networking). +That ordering — and "the real work" — is about the original **consolidation**: +the launch-broker shim and wiring the orchestrator into a VM. The later +orchestrator/gateway **split** (§"Separating the planes") is a smaller, separate +change, and its per-backend difficulty runs the *other* way: docker/macOS carry +the real work (a new control network, a dual-homed gateway, the token-only→L3 +isolation upgrade), while on Firecracker the isolation is nearly free (re-point +one DNAT rule) and the only effort is a mechanical second infra VM. Firecracker +is not the hard part of the split. + Keep the gateway **service one shared thing** throughout. ## Non-goals