diff --git a/docs/CURRENT-STATE.md b/docs/CURRENT-STATE.md index b3a11bb..34f7adb 100644 --- a/docs/CURRENT-STATE.md +++ b/docs/CURRENT-STATE.md @@ -2013,6 +2013,25 @@ at `life: dead`** -- that moved it BACK to `dying` and re-armed the undertaker loop. It did not help and it changed state. Both are now written into Path M as explicit prohibitions. + **>>> D-141 ADOPTED 2026-08-03 (GA-R5): IPAM ALLOCATIONS ARE DUAL-STACK, STATUS-DISTINGUISHED + -- v4 `active`, v6 `reserved` UNTIL THE STACK IS CAPABLE. <<<** Operator, exact utterance: + *"Yes, but you should expand on the record. It should be noted that when creating future ipam + allocations the IPv4 and IPv6 blocks must follow this same structure."* IMMEDIATE effect: the + 26 GUA v6 VIP addresses D-139 step 6 created STAY in the apex at status `reserved` (already + their measured state -- NO NetBox mutation needed), never promoted to `active` until the v6 + VIPs are live and verified. STANDING RULE (the architectural half, and why it is a D-number): + every IPAM allocation is authored DUAL-STACK, and the STATUS field carries the truth -- + v4 `active` (live), GUA v6 `reserved` (planned/collision-protected), superseded ULA + `deprecated` (history). The apex thus records current reality AND future plan in one place, + legible from status alone -- apex driving deploy, not back-filled to it. Full text + + the four binding rules (author both families together; status bears truth never prose; + promotion gated on a NAMED capability; never delete a reserved future-family block): + `docs/design-decisions.md` D-141. **Adjacent to G18 (IPAM apex completeness) but does NOT + answer it** -- D-141 governs allocation STRUCTURE; G18 is the separate lb-mgmt-prefix ruling, + still deferred-until-live. Promotion gate for the API-charm v6 VIPs is the two-layer set in + `docs/charm-ip-family-compatibility.md` (juju LP #1723240 + the per-charm fixes). Next-free D + advances 141 -> 142. + **>>> CONVERGENCE UPDATE 2026-08-03 05:08Z: THE PACKAGE-INSTALL BLOCKER IS GONE; A KNOWN IPv6 CONDITION SURFACED. <<<** 8/9 machines `started`, 6 units `active`, **ZERO units in `error`** -- the first deploy had NINE at `hook failed: "install"` from `NO_PUBKEY`, so the diff --git a/docs/charm-ip-family-compatibility.md b/docs/charm-ip-family-compatibility.md index 909f38d..63043dd 100644 --- a/docs/charm-ip-family-compatibility.md +++ b/docs/charm-ip-family-compatibility.md @@ -10,6 +10,15 @@ --- +## Governing decision + +**D-141 (ADOPTED 2026-08-03)** makes IPAM allocations dual-stack and status-distinguished: +v4 `active`, GUA v6 `reserved` until the consuming layer is capable. **This table IS the +named promotion gate for the API-charm v6 VIPs** -- a `reserved` v6 VIP block moves to +`active` only when both blocker layers below clear. See `docs/design-decisions.md` D-141. + +--- + ## READ THIS FIRST -- v6 is blocked at TWO independent layers A charm being "IPv6-capable" does not make the deployed cloud v6. Two separate things block diff --git a/docs/design-decisions.md b/docs/design-decisions.md index 4103081..5e0e6ae 100644 --- a/docs/design-decisions.md +++ b/docs/design-decisions.md @@ -7540,3 +7540,57 @@ prevent an allocation; it signals one should not be made. The functional protection against handing out an in-use GUA address comes from step 1 above -- the 26 GUA records EXISTING -- not from the deprecation. + +## D-141: IPAM allocations are DUAL-STACK, status-distinguished -- v4 active, v6 reserved-until-capable [ARCH] + +**Status: ADOPTED 2026-08-03 (operator ruling, GA-R5).** Question as presented: with the +container-hosted API charms reverting to IPv4 VIPs (juju LP #1723240 gives containers no v6 +address; hacluster/mysql/ceph-osd/OVN carry their own v6 defects -- see +`docs/charm-ip-family-compatibility.md`), should the v6 VIP allocation be KEPT in the NetBox +apex for future v4->v6 conversion when compatibility catches up? **Operator answer, exact +utterance: "Yes, but you should expand on the record. It should be noted that when creating +future ipam allocations the IPv4 and IPv6 blocks must follow this same structure."** + +**RULED -- the immediate decision:** the GUA v6 VIP allocation STAYS in the apex. No NetBox +mutation is needed: D-139 step 6 already CREATED the 26 GUA VIP addresses and they carry +status **`reserved`** (measured), which is the truth-bearing state -- allocated and held +against collision, but NOT asserted as live. They are NOT promoted to `active` until the v6 +VIPs are actually deployed and verified. + +**RULED -- the STANDING RULE, which is the architectural half and the reason this is a +D-number (GA-R3 A1 test: a future/Roosevelt build session greps this before making any IPAM +allocation):** **every IPAM allocation is authored DUAL-STACK, and the STATUS field carries +the truth about which family is live.** The structure is: + +| Family | NetBox status | Meaning | +|---|---|---| +| IPv4 | `active` | live, deployed, consumed by the running cloud | +| IPv6 (GUA) | `reserved` | carved and collision-protected; planned for conversion when the stack is capable | +| superseded (e.g. ULA) | `deprecated` | history; advisory-only, do not allocate | + +**This makes the apex record BOTH current reality and future plan in one place, legible from +the status field alone.** It is the apex driving the deploy (intent recorded first, deploy +consumes when able), NOT the apex back-filled to match a deploy -- the authority direction +G18/lens-7 requires. + +**RULES that follow, binding on all future allocations:** +1. **Author v4 and v6 together.** A new plane, VIP band, pool or reservation is carved in + BOTH families at allocation time, not v4-now-v6-later. The v6 block mirrors the v4 block's + structure (same host numbering within each family's prefix). +2. **Status bears the truth, never prose.** `active` means live. `reserved` means planned, + not deployed. Never mark a family `active` before it is deployed and verified -- that is + the "apex says built when it isn't" defect this repo has hit (RULED-not-BUILT class). +3. **Promotion is gated on capability, and the gate is named.** A `reserved` v6 block moves to + `active` only when the consuming layer can use it. For the API-charm VIPs that gate is the + two-layer set in `docs/charm-ip-family-compatibility.md` (juju addressing LP #1723240 + + the per-charm fixes). A reserved block SHOULD carry a note pointing at what unblocks it. +4. **Never delete a reserved future-family allocation to "clean up".** It is the conversion + input; deleting it forces a re-carve and frees the address to collide. + +**Relationships:** consumes the D-111 per-DC v6 subcarve and the D-139 GUA family as the v6 +side; the reserved-not-deleted discipline is the D-139 step-6 pattern generalised. +**Adjacent to gate G18** (IPAM apex completeness, deferred-until-live): D-141 governs the +STRUCTURE of apex allocations; G18 remains the separate ruling on the charm-created lb-mgmt +prefix and must not be treated as answered by this. Roosevelt analog: every bare-metal DC's +IPAM is authored dual-stack from day one, v6 reserved until the platform is v6-capable, so no +DC ever needs a v4->v6 re-carve -- only a status promotion.