Fork: 0
OpenStack / openstack-caracal-dc-dc
Transfer to URL with SHA Find file
Newer
Older
openstack-caracal-dc-dc / docs / changelog-20260715-docfix195-c2-netbox-of-record.md
@JANeumatrix JANeumatrix 17 hours ago 5 KB DOCFIX-195: office1-netbox holds the VR1 IPAM apex role; apex write-back deferred; C2 redefined
Raw Blame History

2026-07-15 -- DOCFIX-195: office1-netbox holds the VR1 IPAM APEX role (working draft); apex write-back deferred; C2 redefined

Why

Operator ruling (2026-07-15): office1-netbox (10.10.1.10) HOLDS THE IPAM APEX ROLE during VR1 -- it is the authoritative NetBox every consuming system (OpenTofu, MAAS, overlays, the Juju bundle) derives its values from. It is a working draft (edited as the buildout proceeds), but it is the apex. netbox.baldurkeep.com does not get a write at all during VR1; it is the eventual production apex, frozen as a READ-ONLY v1 reference draft and not consulted by VR1 systems. Merging office1-netbox back into netbox.baldurkeep.com is a deferred maybe at the very end -- NOT a Stage 2 gate.

Confirmed while scoping: no live system config points at any NetBox URL (opentofu/, scripts/, lib-*.sh carry none) -- "consuming systems use office1-netbox as apex" is a value-DERIVATION workflow (we read NetBox by hand to populate lib-net.sh/tfvars/bundle), not a live API wiring, so no config repoint is needed; this is a documentation change only.

The repo encoded the OPPOSITE model: it called netbox.baldurkeep.com the "apex/source of truth" and office1-netbox a throwaway "sandbox", and defined close-out C2 (the last open Stage 2 gate, and the branch->main merge trigger) as an operator-gated write that feeds the carve UPSTREAM. Under the ruling that write does not happen in Stage 2, so C2-as-written was wrong.

Finding surfaced while drafting (new, previously unlogged): D-120 Step 6 registers 10.10.1.0/24's child ranges (ipam/ip-ranges) and the two service IPs (ipam/ip-addresses). Those object classes are NOT covered by the sandbox loop -- prod-draft-dump.py's ENDPOINTS and sandbox-fidelity-check.py's KEY/EXPECTED_NEW both stop at rirs/roles/regions/sites/aggregates/prefixes. So the hardened fidelity check cannot verify the D-120 load; that verification needs a tool extension (+ harness) or a recorded manual read-back. C2 now records this as a tooling gap and an open C2-execution sub-question.

This is a DOCFIX, not a D-NNN: it defers the apex WRITE and does not revoke D-010 (netbox.baldurkeep.com remains the eventual source of truth). Doc-only; no script or live-cloud change.

What changed (all documentation)

  1. docs/dc-dc-deployment-workflow.md -- Stage 2 State-paragraph NetBox bullet + the C2 row. C2 redefined: office1-netbox holds the COMPLETE validated dataset (carve + roles + both DCs + the D-120 child ranges + service IPs), verified by (i) a hardened-fidelity-check re-run on the shared objects and (ii) a load+verify of the D-120 objects; the tooling gap is logged; apex write-back deferred. C2 stays OPEN.
  2. docs/dc-dc-netbox-buildout-scope.md -- section 8.1 (inverted the upstream/office1 roles: office1 is the record, the apex is a read-only v1 draft, merge-back deferred) and section 8.6 (retitled and rewritten from "Feeding the delta upstream" to "office1-netbox holds the validated dataset; apex write-back DEFERRED", with the D-120 tooling gap and the deferred-merge-back procedure).
  3. docs/session-ledger.md -- five spots corrected (D-120 Step 6 item; OPEN-WORK item 2; the NetBox WRITE-PATH BUGS preamble; the fidelity-recheck sequence note; the PINNED merge-point bullet) plus a NEW PINNED bullet recording the deferred apex write-back. All edits are in narrative sections; the machine-derived block was not touched.
  4. docs/design-decisions.md -- a dated Note under D-010 recording the VR1-phase apex role (office1-netbox is the working-draft apex; apex write-back deferred; defers the write, does not revoke D-010), AND a pointer on D-103's "NetBox remains the IPAM apex; MAAS and overlays consume NetBox values" bullet naming office1-netbox as that apex during VR1.
  5. netbox/README.md -- a banner so the NETBOX_URL=https://netbox.baldurkeep.com examples are not mistaken for the VR1 write target (that is office1-netbox; the apex URL is for the deferred merge-back only, gated by --yes-write-upstream).

Also logged (NOT actioned here)

  • Tooling gap: the sandbox dumper + fidelity check do not cover ip-ranges/ip-addresses; the D-120 load cannot be machine-verified until they are extended (each with its harness) or a manual read-back is recorded. This is the real remaining C2-execution work.
  • Durability finding: office1-netbox is now load-bearing VR1 IPAM state on a lab VM; its backup/durability matters once it is the record (log-only; not part of this DOCFIX).

Revert

Each item is an isolated text edit; revert individually:

  1. git checkout HEAD -- docs/dc-dc-deployment-workflow.md
  2. git checkout HEAD -- docs/dc-dc-netbox-buildout-scope.md
  3. git checkout HEAD -- docs/session-ledger.md
  4. git checkout HEAD -- docs/design-decisions.md
  5. git checkout HEAD -- netbox/README.md
  6. git rm docs/changelog-20260715-docfix195-c2-netbox-of-record.md

Reverting restores the prior "feed the carve upstream = C2" framing across all five docs. No code paths, scripts, harnesses, or live NetBox state are affected by this change or its revert.