diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index e7d89b1..8968e69 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -1102,6 +1102,32 @@ the mapping unruled; mirroring the v4 octet is well-defined for the ULA metal legs but genuinely ambiguous for the GUA provider leg, which has a DEDICATED VIP `/64` (`f02:11::50` mirroring the octet, or `f02:11::1` first-in-block?). +- **D-136 ADOPTED 2026-07-27 -- OPTION (D); and the IPv6 HOST-PART CONVENTION RULED.** Operator + utterance, quoted verbatim in BOTH entries: **"Rule D-136 option D, mirror the v4 octet for + both legs but make a note to review at the end of the project to review for adjustment."** + **GA-R5 NOTE, recorded rather than glossed: this single exchange carried TWO rulings**, and + GA-R5 says one per exchange with batch adoptions invalid. Both were recorded because each + clause is a specific, unambiguous answer to a specific question already put -- not a template + "yes to all", which is the class GA-R5 exists to reject. Flagged to the operator for + confirmation; if either is to be re-put separately it will be re-taken. + **(1) D-136 is ADOPTED at option (D)** -- and option (D) was WRITTEN INTO the entry before + being adopted, because the directed shape matched none of the recorded (A)/(B)/(C) and + adopting an option the entry did not contain would leave a future reader unable to find what + was decided. (D) = populate the apex FIRST, then build the renderer, then dry-run it WITHOUT + gating this deployment on it. It differs from (C) by closing the apex gap now rather than + keeping VIPs/bands hand-maintained indefinitely, and from (A) by keeping an unproven tool off + the deploy's critical path. Implementation is UNBLOCKED; F2/F3 remain out of build scope. + **(2) The IPv6 host part MIRRORS THE V4 OCTET ON BOTH LEG TYPES** -- ULA metal and GUA + provider alike -- closing the mapping R4's D-134 amendment left explicitly unruled and + unblocking the value population that nothing could proceed without (the apex carries every v6 + PREFIX and ZERO per-address v6 objects). So keystone `.50` is `2602:f3e2:f02:11::50` / + `fd50:840e:74e2:220::50` / `:221::50` in dc0, same host parts under dc1's prefixes. Recorded + under D-134's R4 amendment, which is the authority. ACCEPTED COST, deliberate not overlooked: + the GUA leg's DEDICATED VIP `/64` is then used from `::50` up, leaving `::1`-`::49` unused -- + the price of ONE rule per plane instead of a per-leg special case in the renderer. + **REVIEW OWED AT THE CLOSE OF THIS DEPLOYMENT** (same utterance) -- forward item **F4** in + `docs/dc-dc-deployment-workflow.md`, whose trigger is the END OF THIS deployment, unlike + F1-F3. Cheap to change by construction: a renderer input change plus a re-render. - Position inside Stage 3: deploy step A EXECUTED 2026-07-19 (6/0/6 exact; convergence zero -- `docs/audit/outer-plan-20260719-postA-converged.txt`). **Deploy step B diff --git a/docs/dc-dc-deployment-workflow.md b/docs/dc-dc-deployment-workflow.md index c18cc2a..5d148fd 100644 --- a/docs/dc-dc-deployment-workflow.md +++ b/docs/dc-dc-deployment-workflow.md @@ -260,7 +260,11 @@ --- -## Forward items -- DEFERRED BY RULING to the next deployment +## Forward items -- DEFERRED BY RULING + +Each item carries its OWN trigger. F1-F3 are deferred to the NEXT deployment; **F4 is due at +the END OF THIS ONE.** Check the trigger before assuming an item is out of scope for the +current work. Named forward items live HERE, not as D-numbers. GA-R3 rule 1(b) as amended by A1 is explicit: "Mentioning Roosevelt, or recording a Roosevelt-era preference, does not @@ -364,6 +368,32 @@ NAME -> MAAS subnet by CIDR, never by VLAN/fabric/subnet id. This layer is MAAS-sourced; NetBox is IPAM only. +### F4. IPv6 GUA host-part packing -- REVIEW AT THE END OF *THIS* DEPLOYMENT + +**TRIGGER: end of THIS deployment, not the next.** Unlike F1-F3. + +**Owed by ruling, 2026-07-27** (operator: "mirror the v4 octet for both legs but make a note +to review at the end of the project to review for adjustment"). The ruling is recorded under +D-134's R4 amendment in `docs/design-decisions.md`, which is the authority. + +**What was ruled:** the v4 octet is mirrored as the IPv6 host part on BOTH leg types -- the +ULA metal legs AND the GUA provider leg. keystone at v4 `.50` is `::50` everywhere. + +**What to review, and why it is worth a look:** the GUA provider leg has a DEDICATED VIP +`/64` per DC (`2602:f3e2:f02:11::/64` dc0, `f03:11::/64` dc1) with no node statics competing +for space. Mirroring the octet means that block is used from `::50` upward and `::1`-`::49` +sit unused. That was chosen deliberately -- ONE rule for every plane, so a VIP's host part is +predictable from its v4 octet and checkable by eye and by gate -- rather than carrying a +per-leg special case in the renderer. The review question is whether, with the cloud live and +v6 behaviour observed, the GUA leg should instead pack from `::1`. + +**Cheap to change, by construction:** because the convention is uniform, adjusting it is a +renderer INPUT change plus a re-render, not a redesign. That is the main reason the uniform +rule was affordable to adopt first and review later. + +**Related:** G18 (also project-close blocking) covers a different apex question -- whether the +charm-created Octavia `lb-mgmt-net` prefix is back-filled into NetBox. Do not conflate them. + --- ## Cross-cutting discipline (applies at every stage, every session) diff --git a/docs/design-decisions.md b/docs/design-decisions.md index 3c0e949..c3a1e95 100644 --- a/docs/design-decisions.md +++ b/docs/design-decisions.md @@ -5357,6 +5357,45 @@ mapping is NOT ruled here -- it lands with the carve, and mirroring the v4 host-part layout is the obvious mechanical default rather than a fresh design question. +**IPv6 HOST-PART CONVENTION RULED 2026-07-27 (GA-R5) -- this closes the mapping the +paragraph above left open.** Question as presented: the v6 host part is unruled and the apex +carries every v6 PREFIX but ZERO per-address v6 objects, so nothing can be populated without +it. Mirroring the v4 octet is well-defined for the ULA metal legs, which have one `/64` per +plane shared with node statics -- but is genuinely ambiguous for the GUA provider leg, which +has a DEDICATED VIP `/64` (`2602:f3e2:f02:11::/64` dc0, `f03:11::/64` dc1) separate from its +node `/64` at `:10::/64`: does keystone take `f02:11::50`, mirroring the octet, or +`f02:11::1`, first-in-a-dedicated-block? Operator answer, exact utterance: **"Rule D-136 +option D, mirror the v4 octet for both legs but make a note to review at the end of the +project to review for adjustment."** (The first clause of that utterance rules D-136; this +entry records the second.) + +**EFFECT: the v4 octet is mirrored on BOTH legs -- ULA and GUA alike.** So an application at +v4 octet `X` takes host part `::X` in every v6 plane: + +| app | octet | dc0 v6 triple (provider GUA / metal-admin ULA / metal-internal ULA) | +|---|---|---| +| keystone | 50 | `2602:f3e2:f02:11::50` `fd50:840e:74e2:220::50` `fd50:840e:74e2:221::50` | +| ceph-radosgw | 60 | `...f02:11::60` `...:220::60` `...:221::60` | +| vault | 61 | `...f02:11::61` `...:220::61` `...:221::61` | +| designate | 62 | `...f02:11::62` `...:220::62` `...:221::62` | + +dc1 is the same host parts under its own prefixes (`2602:f3e2:f03:11::/64`, +`fd50:840e:74e2:320::/64`, `:321::/64`). **Rationale as ruled: ONE rule for every plane.** +The alternative -- octet-mirroring on ULA and first-in-block on GUA -- would have made the +renderer carry a per-leg special case and made every VIP's host part unpredictable from its +v4 octet, which is the property that makes the mapping checkable by eye and by gate. +**Accepted cost, and the reason for the review below:** on the GUA leg the dedicated VIP +`/64` is then used from `::50` upward rather than from `::1`, so `::1`-`::49` sit unused in a +block that has no node statics competing for them. That is deliberate consistency, not an +oversight. + +**REVIEW OWED AT PROJECT CLOSE, by the same ruling** ("make a note to review at the end of +the project to review for adjustment"): revisit whether the GUA leg should instead pack from +`::1`, once the cloud is live and the v6 behaviour has been observed. Recorded as forward +item **F4** in `docs/dc-dc-deployment-workflow.md`, whose trigger is the END OF THIS +DEPLOYMENT -- not the next one, unlike F1-F3. Adjusting it later is a renderer input change +plus a re-render, not a redesign, precisely because the convention is uniform. + **Execution is a SEPARATE gated step, not authorised by this amendment.** Standard delivery discipline applies: the tool ships with its `tests//run-tests.sh` green, gauntlet ALL GREEN, repo-lint 0-fail, and a changelog entry carrying a revert. The reservation pass @@ -5454,8 +5493,20 @@ ## D-136: NetBox-coupled per-DC render pipeline for bundle overlays and tfvars [ARCH] -**Status:** PROPOSED 2026-07-25 (Chat design seat, repo HEAD bc9a2df; operator has not -ruled on the mechanism). Escalates the renderer deferral in +**Status:** **ADOPTED 2026-07-27 -- option (D)** (GA-R5). Question as presented: options (A) +build-the-generator-now-and-gate-the-deploy, (B) hand-render-now-generator-for-Roosevelt, or +(C) values-file back half now with the NetBox front half later -- noting the operator had +directed a shape matching NONE of the three: populate the apex FIRST, then build the renderer, +then dry-run it WITHOUT gating this deployment on it. That shape was written up as **option (D) +below** so the ruling would not adopt something the entry did not contain. Operator answer, +exact utterance: **"Rule D-136 option D, mirror the v4 octet for both legs but make a note to +review at the end of the project to review for adjustment."** (The second clause of that +utterance rules the IPv6 host-part convention, recorded under D-134's R4 amendment, not here.) +IMPLEMENTATION IS UNBLOCKED. The carve-outs agreed the same day are pinned as forward items +**F2** (the automation half -- CI runner, event delivery, status-back) and **F3** (the MAC/VLAN +scope boundary) in `docs/dc-dc-deployment-workflow.md`; both are OUT of this adoption's build +scope. Prior status, kept as history: PROPOSED 2026-07-25 (Chat design seat, repo HEAD bc9a2df). +Escalates the renderer deferral in `docs/audit/committee-20260724-track2-bundle-render.md` (Fork 2, "hand-render dc1 now, extract the tool when dc0 forces the second render") to a NetBox-coupled generator. Supersedes nothing. @@ -5542,7 +5593,32 @@ substitution step. Both DCs ship on it. The NetBox front half (record -> values file) is added later without touching the back half, because the interface is frozen. -**Why (C).** It captures the whole benefit -- one source of truth, no two lists to +- **(D) Populate the apex FIRST, then build the renderer, then dry-run it -- WITHOUT gating + this deployment on it. ADOPTED 2026-07-27.** Added to this entry on the day it was ruled, + because the operator's directed shape matched none of (A)/(B)/(C) and adopting an option the + entry did not contain would leave a future reader unable to find what was decided. + Order: (1) make the gates trustworthy, (2) reconcile the values, (3) import them into every + authoritative source -- MAAS, `lib-net.sh`, and the apex -- *even where the value was + hand-written before the source existed*, (4) build the renderer, (5) dry-run it to confirm it + pulls correctly *even though the data is already in place*, (6) audit the + `data source -> renderer -> deployment mechanism` chain. + **How it differs from (C):** (C) defers the NetBox front half and keeps VIPs/bands in a + hand-maintained values file indefinitely; (D) closes the apex gap NOW, so the values file is + transitional in fact and not just in intent. **How it differs from (A):** (A) puts an unproven + tool on the deploy's critical path; (D) explicitly does not -- the renderer is dry-run and its + output reviewed, and this deployment can proceed on reviewed artifacts regardless. + **Why the deploy is not delayed by it:** the deploy is already blocked on the controller VM, + per-role tags, OSD devices, v6 carve and dc0's missing overlays -- all of which are the + renderer's own INPUTS. The tool work does not compete with the deploy for the critical path. + **Cost, stated honestly:** the front half is built against an apex schema that only exists + once step (3) lands, so (3) must complete before (4)'s front half is written -- which is the + ordering the ruling already specifies. **Validation advantage over both (A) and (C):** the + renderer is first proven by REPRODUCTION against `tests/render-baseline/` -- the known-good + v4 11-application artifacts frozen 2026-07-27 precisely because the R2/R11 reconciliation + destroys them. (A) has no such baseline; the fixtures make (D) checkable. + +**Why (C).** [Superseded as the recommendation by the (D) adoption above; retained because its +reasoning is what (D) builds on.] It captures the whole benefit -- one source of truth, no two lists to drift -- without absorbing the front half's unknowns (VIP representability, MAC and VLAN buildout, token handling, network reach), none of which are on this deploy's critical path. It makes the front half testable BY REPRODUCTION: once the schema is diff --git a/docs/session-ledger.md b/docs/session-ledger.md index b1de5a6..65cc7ef 100644 --- a/docs/session-ledger.md +++ b/docs/session-ledger.md @@ -33,12 +33,13 @@ _Re-seeded from a 2026-07-27 scan at the STAGE 4 CLOSE (values verified against `bash scripts/ledger-scan.sh` in that session). Re-run the scan to refresh._ -- **PROPOSED / OPEN decisions (4):** D-068 (Vault substrate hardening, Roosevelt -- sole +- **PROPOSED / OPEN decisions (3):** D-068 (Vault substrate hardening, Roosevelt -- sole remainder is Q2 path selection at Roosevelt Vault design time), D-131 (node-facing DNS for rack-only controllers [ARCH] -- sub-4 open + the pinned DNS architectural review), D-132 - (Roosevelt per-DC MAAS topology [ARCH], operator-pinned to the next deployment), D-136 - (NetBox-coupled per-DC render pipeline [ARCH], non-gating). D-137 is ADOPTED and correctly - drops off the scan. Status lines in `docs/design-decisions.md` are the only ruling authority. + (Roosevelt per-DC MAAS topology [ARCH], operator-pinned to the next deployment). + **D-136 was ADOPTED 2026-07-27 at option (D)** and correctly drops off the scan, as D-137 + did before it (was 4). Status lines in `docs/design-decisions.md` are the only ruling + authority. - **OPEN security rows:** **21** per `bash scripts/ledger-scan.sh` (was 20). SEC-025 opened 2026-07-27 -- the NetBox web-GUI `admin` password, a HUMAN login that had never left the VM it was minted on, now consolidated to `~/vr1-office1-creds/`; the row covers the at-rest