diff --git a/docs/design-decisions.md b/docs/design-decisions.md index dbb2d63..67783a5 100644 --- a/docs/design-decisions.md +++ b/docs/design-decisions.md @@ -3152,3 +3152,67 @@ The one durable lesson of D-117 -- which survives its completion -- is that an unqualified `dcN` in a repo that operates more than one cloud is a latent off-by-one waiting for a reader who does not know which cloud the sentence is about. + +## D-120: static-services addressing convention for the MAAS-managed compose /24s (PROPOSED) + +**Status:** **PROPOSED 2026-07-15.** Operator endorsed the direction (static services belong in a low +band, not mixed with deployed nodes); this entry ratifies the exact band boundaries and the Office1 +service addresses. Refines D-115 (which ratified that `10.10.1.0/24` exists as the Office1 compose +net but left its INTERNAL layout as just "MAAS DHCP/PXE"). Does NOT reopen D-115's /22 carve. + +### The problem + +On `10.10.1.0/24` (Office1 `lxdbr0`, MAAS-managed), the persistent site services sit at +`office1-netbox = 10.10.1.201` and `office1-tailscale = 10.10.1.202` -- addressed IDENTICALLY to how +a deployed OpenStack node would be. MAAS auto-assigns deployed machines from `.201+` (just past its +`.100-.200` dynamic range), so the services landed there by default, not by design. They are NOT in +the DHCP dynamic range (no collision), but they are not distinguishable from ephemeral compute nodes +either. There is no ratified sub-layout for the /24. + +### Decision (PROPOSED) -- a functional band layout for EVERY MAAS-managed compose /24 + +Applies to Office1's `10.10.1.0/24` AND to each DC's compose /24 when the DCs are built (they inherit +the template -- minimize-delta): + + .1 gateway (the site containment VM: voffice1, and each DC's equivalent) + .2 - .49 STATIC site infrastructure/services (MAAS static-assign; OUTSIDE the dynamic range) + .50 - .99 reserved / spare (headroom for more static services) + .100 - .200 MAAS DYNAMIC (enlistment / commissioning / PXE / DHCP) [as already deployed] + .201 - .254 deployed compute / OpenStack nodes (MAAS auto-assign) [as already deployed] + +The dynamic and node bands are UNCHANGED from what MAAS already does -- only the static-services band +`.2-.49` is newly reserved, and it already sits outside the dynamic range, so no MAAS range edit is +needed, only per-service static IP assignment. + +### Office1 service addresses (PROPOSED; operator to ratify) + + office1-netbox 10.10.1.201 -> 10.10.1.10 + office1-tailscale 10.10.1.202 -> 10.10.1.11 + +`.10`/`.11` are arbitrary within `.2-.49`; chosen low and adjacent. Operator may pick otherwise. + +### Recording it in NetBox (the IPAM authority deciding where NetBox itself lives) + +The band layout is a carve that belongs IN NetBox: register `10.10.1.0/24`'s child ranges (static / +dynamic / node) and the two service IP assignments. Do this through the sandbox loop (D-115 / the +C4-documented loop), not by hand -- NetBox is the authority for exactly this. + +### Consequence / cost (why this is not a free change) + +Re-IPing Office1's two RUNNING services cascades to 20 repo references, INCLUDING the hardcoded +`SANDBOX_HOSTS = {localhost, 127.0.0.1, 10.10.1.201}` allowlist in `roles-aggregates-import.py` and +`dc-dc-prefixes-import.py` (added 2026-07-14) plus its test. See the re-IP plan +(`runbooks/dc-dc-office1-service-reip.md`). It is a gated mutation on live services, not done here. + +### Options + +- **(a) ADOPT the convention AND re-IP Office1 now** (recommended) -- Office1 is the proven template; + making it match means the DCs inherit a clean, already-exercised layout. Cost: a gated re-IP of two + running services + the 20-reference sweep. +- **(b) ADOPT the convention for the DCs ONLY; leave Office1 at `.201/.202`** -- zero disruption now, + but Office1 (the template everyone copies) permanently diverges from the convention, and the + `SANDBOX_HOSTS` allowlist keeps a "deployed-node-band" address for a static service. +- **(c) Reject** -- keep services in the node band. Not recommended: it is the ambiguity this entry + exists to remove. + +**Recommendation: (a).** Get the template right once. diff --git a/docs/session-ledger.md b/docs/session-ledger.md index 3baca9d..38790ef 100644 --- a/docs/session-ledger.md +++ b/docs/session-ledger.md @@ -88,6 +88,16 @@ ## OPEN WORK -- VR1 DC-DC (the current mission) +**D-120 PROPOSED (2026-07-15) -- static-services addressing for the compose /24s.** Office1's +`office1-netbox` (10.10.1.201) and `office1-tailscale` (10.10.1.202) sit in MAAS's deployed-node +band, not distinguishable from ephemeral nodes. D-120 proposes a functional band layout +(`.2-.49` static services / `.100-.200` dynamic / `.201+` nodes) for every MAAS compose /24, and +re-IPing Office1's two services to `.10`/`.11`. **AWAITS operator ratification of the addresses.** +Re-IP plan written: `runbooks/dc-dc-office1-service-reip.md` (gated; NOT executed). Cascades to 20 +repo refs incl. the hardcoded `SANDBOX_HOSTS` `.201` in two importers. DCs inherit the layout from +day one. This is a NEW open item, separate from Stage 2 close-out (C2 is still the only C-item left). + + The authoritative per-stage tracker is `docs/dc-dc-deployment-workflow.md` (stage table + tooling gap register). Read it FIRST. This list is only what that doc does not already carry. diff --git a/runbooks/dc-dc-office1-service-reip.md b/runbooks/dc-dc-office1-service-reip.md new file mode 100644 index 0000000..d44f835 --- /dev/null +++ b/runbooks/dc-dc-office1-service-reip.md @@ -0,0 +1,90 @@ +# Office1 service re-IP -- move NetBox + Tailscale into the D-120 static band + +**Gated mutation on TWO RUNNING services.** Do not run until **D-120 is ADOPTED** (the operator has +ratified the band layout AND the target addresses). Present each step, justify it as minimal, get +individual approval. This is also the reference procedure the DCs reuse for their own compose /24s. + +## Target (D-120 PROPOSED; confirm against the adopted decision before running) + + office1-netbox 10.10.1.201 -> 10.10.1.10 (static, band .2-.49) + office1-tailscale 10.10.1.202 -> 10.10.1.11 (static, band .2-.49) + +Both VMs are MAAS-COMPOSED LXD VMs on `voffice1`; their addresses come from MAAS. The edge's static +route `10.10.1.0/24 -> 10.10.0.20` is /24-wide and is UNAFFECTED by the change. + +## Preconditions (READ-ONLY) + +1. D-120 ADOPTED; target addresses confirmed. +2. Coordinate with sandbox/C2 work -- the NetBox re-IP briefly interrupts the sandbox NetBox. +3. Record current state: `office1-netbox 10.10.1.201`, `office1-tailscale 10.10.1.202` (as-built). +4. Access: `ssh -J jessea123@10.10.0.20 ubuntu@10.10.1.201` (and `.202`); MAAS on `voffice1` + (`10.10.0.20`), secrets in `/root/maas-secrets/` on the box (operator-held). + +## Step 1 -- MAAS: static-assign the new address to each VM's interface [MUTATION: gated] + +For each machine, set its interface on the `10.10.1.0/24` subnet to **static-assign** the target +address (a fixed IP outside MAAS's `.100-.200` dynamic range). The `.2-.49` band is already outside +the dynamic range, so NO dynamic-range edit is required. + + Network -> the interface on + 10.10.1.0/24 -> Edit -> Mode = "Static assign" -> IP = 10.10.1.10 (netbox) / .11 (tailscale). + CLI form is roughly `maas $PROFILE interface link-subnet mode=STATIC + subnet= ip_address=10.10.1.10` -- CONFIRM the subcommand/args against the installed + MAAS 3.7 before running; do not run a guessed command against live MAAS.> + +## Step 2 -- Apply the new address on the VM [MUTATION: gated] + +A composed VM picks up the MAAS assignment on a network reconfigure or redeploy. + + + +## Step 3 -- Fix each SERVICE's own address config [MUTATION: gated] + +- **NetBox (`office1-netbox`, netbox-docker):** NetBox binds `0.0.0.0:8000`, so it follows the host + IP -- BUT `ALLOWED_HOSTS` / `CSRF_TRUSTED_ORIGINS` may name the old `10.10.1.201`. + `` +- **Tailscale (`office1-tailscale`):** it advertises `10.10.0.0/22` as a subnet router; the ADVERTISED + routes do not change, but its own LAN interface address does. `` + +## Step 4 -- Verify on the wire (READ-ONLY) + + ssh -J jessea123@10.10.0.20 ubuntu@10.10.1.10 'ip -4 addr' # netbox at .10 + curl -s -o /dev/null -w "%{http_code}\n" http://10.10.1.10:8000/api/ # 403/200 = up + ssh -J jessea123@10.10.0.20 ubuntu@10.10.1.11 'tailscale status' # tailscale at .11 + +## Step 5 -- Update the 20 repo references + the importer allowlist [repo change; gated] + +`10.10.1.201 -> 10.10.1.10` and `10.10.1.202 -> 10.10.1.11` across (measured 2026-07-15): + +- **CODE (must, or the guard breaks):** `SANDBOX_HOSTS` in `netbox/roles-aggregates-import.py` and + `netbox/dc-dc-prefixes-import.py` (the `.201` entry -> `.10`); `netbox/d115-office-carve.py`'s + `SANDBOX_HOSTS`; `tests/dc-dc-prefixes-import/test_logic.py` (the sandbox-URL host it sets); + `tests/roles-aggregates-import/run-tests.sh` (the SANDBOX_HOSTS assertion). +- **Docs (forward-looking):** `docs/vr1-office1-as-built.md`, `docs/session-ledger.md`, + `docs/dc-dc-netbox-buildout-scope.md`, `docs/dc-dc-deployment-workflow.md`, + `runbooks/dc-dc-phase1-office1-standup.md`. Leave dated changelogs as historical snapshots. +- Re-run `bash scripts/run-tests-all.sh` (the SANDBOX_HOSTS harnesses must stay green) + `repo-lint`. + +## Step 6 -- Record the D-120 carve in NetBox (via the sandbox loop) + +Register `10.10.1.0/24`'s child ranges (static `.2-.49` / dynamic `.100-.200` / node `.201-.254`) and +the two service IP assignments in the sandbox NetBox, then feed upstream with C2. NetBox is the IPAM +authority for this; do not leave the layout recorded only in prose. + +## Rollback + +Re-run Steps 1-3 with the old addresses (`.201`/`.202`), `git revert` the Step-5 repo change. Nothing +here is destructive -- the VMs and their data are untouched; only the L3 address changes. + +## DC replication note + +When a DC's compose /24 is built, its services get D-120 static-band addresses FROM DAY ONE via this +same procedure -- there is no "assign in the node band then re-IP later" for the DCs. This runbook is +the reference.