diff --git a/docs/design-decisions.md b/docs/design-decisions.md index f546332..7a62e65 100644 --- a/docs/design-decisions.md +++ b/docs/design-decisions.md @@ -4,6 +4,14 @@ **Scope split:** This repository implements **v1 (IPv4-only)**. Several decisions below are tagged with **[v2-scope]** — they remain valid design intent but are deferred to a future v2 deployment when upstream router infrastructure supports IPv6. See **D-015** for the v1/v2 fork record. +**Class tags (GA-R3, ratified 2026-07-18; one-time review ruled 2026-07-19).** Every register +entry carries a one-word class tag in its header: **[ARCH]** (architectural consequence beyond +the current stage, a Roosevelt-delta implication per the A1 test, or supersession of an existing +D-number) or **[OPS]** (operational choice recorded here historically; new OPS items get runbook/ +as-built entries, NEVER a new D-number -- GA-R3 rule 2). New entries are ARCH by construction; +doubt resolves DOWN to OPS. Entries D-001..D-120 predate the rule and are tagged opportunistically, +not retroactively swept. + --- @@ -3288,7 +3296,7 @@ The NetBox-side carve record (Step 6 -- register the `.2-.49`/dynamic/node child ranges + the two service IPs in the sandbox, then feed upstream) is still OWED and rides with C2; it is NOT done here. -## D-121: VR1 makes HA real -- scale the decorative single-unit control plane to 3, and the per-DC node layout that carries it +## D-121: VR1 makes HA real -- scale the decorative single-unit control plane to 3, and the per-DC node layout that carries it [ARCH] **Status:** ADOPTED (2026-07-15/16, operator rulings). **Node layout = Option C** (3 control + 2 compute + **4 storage** per DC, **18 node VMs**) -- storage count amended 3->4 per the 2026-07-16 @@ -3471,7 +3479,7 @@ storage/DC = PASS 5.31 TiB. The lost `scratchpad/optc-calc.py` and its "reproducible" changelog claim are retired. -## D-122: VR1 site shape -- nested-per-site containment, dark fiber + dedicated per-site L3 ISP, DC edge follows the Office1 pattern +## D-122: VR1 site shape -- nested-per-site containment, dark fiber + dedicated per-site L3 ISP, DC edge follows the Office1 pattern [ARCH] **Status:** ADOPTED (2026-07-15, operator ruling this session -- answers Stage-3 Ruling 2). Records the deployment shape so Stage 3's edge/network steps stop re-deriving it. Governs @@ -3540,7 +3548,18 @@ re-address, no new NetBox object. (An earlier D-125 draft wrongly said the /24 "moves to a new vcloud-level NAT" and "the old 172.30.2.0/24 is UNUSED" -- corrected 2026-07-16.) -## D-123: VR1 DC site-down DR model -- node-VM placement + the per-DC MAAS headend (resolves a D-122/D-103 tension) +### D-122 -- AMENDMENT (2026-07-19): absorbs D-129's ARCH fragment -- the Roosevelt metal-edge plugin transfer profile (GA-R3/A1 split, operator-ruled) + +Per the GA-R3 one-time review ruling (sweep Batch 2 item 2.7): D-129 is class OPS (a VR1 plugin +install), but its Roosevelt transfer profile is ARCH and moves here, onto the governing site/edge- +shape decision. The profile, verbatim from D-129: **Roosevelt metal edge profile = {`os-smart`, +`os-nut`|`os-apcupsd`, `os-cpu-microcode-intel`/`-amd`, `os-lldpd`}** -- enable at the Roosevelt +edge build (inert on VR1 VMs; hardware-only concerns: disk SMART, UPS, CPU microcode, LLDP +topology). A future Roosevelt build session greps THIS decision for the edge shape and finds the +profile with it. D-129 retains the text historically (append-only); this amendment is the +governing copy. + +## D-123: VR1 DC site-down DR model -- node-VM placement + the per-DC MAAS headend (resolves a D-122/D-103 tension) [ARCH] **Status:** ADOPTED **Model B** (operator ruling 2026-07-16 -- see the AMENDMENT at the end of this entry). The earlier "ADOPTED Model A" (2026-07-15) was INFERRED from "Do it all now" (a @@ -3632,7 +3651,7 @@ retarget `modules/maas-vm-host`. **What still stands:** the MAAS model (ONE region on Office1 + a rack controller per DC -- `vvr1-dc0` is that rack, now also the node host) is operator-confirmed and unaffected. -## D-124: the Office1-region <-> DC-rack management overlay -- addressing for the MAAS control path +## D-124: the Office1-region <-> DC-rack management overlay -- addressing for the MAAS control path [ARCH] **Status:** ADOPTED (2026-07-16, operator ruling). **Scheme A** (transit-numbered mesh) + rack sizing **4 vCPU / 8192 MiB / 80 GiB** confirmed. The office1<->dc0 mesh leg is a point-to-point transit @@ -3710,7 +3729,7 @@ `--commit` runs ON office1-netbox (apex token local there; unreachable from the vcloud jumphost). See `docs/changelog-20260716-d124-addressing-pin.md`. -## D-125: VR1 Model B per-DC ISP egress -- bridge-in single-NAT (resolves OBS-3's design gap; egress efficacy is a deploy-time gate) +## D-125: VR1 Model B per-DC ISP egress -- bridge-in single-NAT (resolves OBS-3's design gap; egress efficacy is a deploy-time gate) [ARCH] **Status:** ADOPTED (operator ruling 2026-07-16 -- "DC0 and DC1 are supposed to have ISP connections", then chose bridge-in over double-NAT). Governs how each DC's simulated ISP uplink (`vr1-dc0-wan`, D-122) @@ -3788,7 +3807,7 @@ DOCFIX-185 (edge is a real-ISP router, not an egress airgap). **Fallback:** `docs/model-a-fallback-plan.md` section 3 (revert removes the uplink NIC/network/bridge + `wan-bridge` and restores the OPNsense WAN addr). -## D-126: durable, rootless vcloud->site-service-VM access -- SSH local-forward via systemd --user (RULED: Option A) +## D-126: durable, rootless vcloud->site-service-VM access -- SSH local-forward via systemd --user (RULED: Option A) [OPS] **Status:** RULED 2026-07-16 (operator chose Option A: "We have been using SSH proxyjump already so lets continue that"). Tooling delivered (`scripts/site-forward.sh` + harness, reviewed-but-UNEXERCISED: this @@ -3911,7 +3930,7 @@ office1` (root) on any host where installed; `git rm scripts/site-baseleg.sh` + its `tests/` dir; delete this amendment. -## D-127: VR1 host-level VM autostart policy -- foundational service VMs autostart, DC containment VMs manual +## D-127: VR1 host-level VM autostart policy -- foundational service VMs autostart, DC containment VMs manual [OPS] **Status:** RULED 2026-07-16 (operator: "set the autostart for the VMs so we don't run into problems if the hosts restart"). Recorded before an OS-update/reboot of the vcloud host; the live `virsh autostart` @@ -3969,7 +3988,7 @@ `resume-guests-state-on-host-boot`). **Revert:** `virsh autostart --disable `; drop the IaC `autostart` args; delete this entry. -## D-128: VR1 operating model -- Claude on the vcloud jumphost; two-plane origin; workstation tailnet is the human path +## D-128: VR1 operating model -- Claude on the vcloud jumphost; two-plane origin; workstation tailnet is the human path [OPS] **Status:** RULED 2026-07-17 (operator: "I will go with your recommendation"). Recorded + folded into the operating skill so no future session re-derives it. Governs WHERE work originates, not any built surface. @@ -4012,7 +4031,7 @@ the operating skill (invariant). **Revert:** delete this entry + the skill invariant; the operating model has no built-surface footprint to unwind. -## D-129: OPNsense edge plugin / add-on base profile (VR1 -> Roosevelt) +## D-129: OPNsense edge plugin / add-on base profile (VR1 -> Roosevelt) [OPS] **Status:** OPEN (PARTIALLY RULED 2026-07-18) -- profile adopted, FOUR sub-decisions still OPEN. Operator directive: "install the OPNsense recommendations and pin the full engineering for the rest for @@ -4107,7 +4126,15 @@ (Designate owns DNS), D-107 (Tailscale subnet-router VM), D-124/D-125 (static transit), D-127 (autostart), D-126 (base-leg). **Revert:** delete this entry + the review doc; nothing was installed. -## D-130: cloudinit seed-volume durable fix -- ignore_changes on the staging-derived create +### D-129 -- AMENDMENT (2026-07-19): class OPS; ARCH fragment split out (GA-R3/A1) + +One-time-review ruling (operator, 2026-07-19): D-129 is tagged **[OPS]** (dominant purpose = the +VR1 plugin install + pins). Its ARCH fragment -- the Roosevelt metal-edge transfer profile -- is +SPLIT to a dated AMENDMENT on D-122 (the governing site/edge-shape ARCH decision), which is now +the governing copy; the text above stays as history (append-only register). The four OPEN +sub-decisions (i)-(iv) are unaffected and remain OPEN on this entry. + +## D-130: cloudinit seed-volume durable fix -- ignore_changes on the staging-derived create [ARCH] **Status:** ADOPTED 2026-07-19 (operator; GA-R5 -- question + utterance below; sweep Batch 1 item 3).