#!/usr/bin/env python3 """ D-139 execution STEP 6, one DC: re-home the v6 VIP ip-addresses from the retiring ULA /64s onto their GUA counterparts, then DEPRECATE the ULA addresses and the ULA prefixes. . ~/vr1-office1-creds/vr1-netbox-sandbox.env # the WORKING VR1 apex (DOCFIX-195) python3 netbox/d139-step6-vip-rehome.py --dc vr1-dc0 # DRY RUN (the default) python3 netbox/d139-step6-vip-rehome.py --dc vr1-dc0 --commit # writes, then reads back TWO OPERATOR RULINGS, both 2026-08-02 (GA-R5), quoted in docs/design-decisions.md: ordering -- "Full step 6 first, then deploy" semantics -- "Deprecate both, delete nothing" NOTHING IS EVER DELETED. "Retire" == status=deprecated. This preserves d139-gua-carve.py's never-delete posture repo-wide -- that refusal is why the step-1 push was safe to run. REVERSIBILITY, STATED PRECISELY because an earlier draft of this docstring overclaimed it: the 26+9 DEPRECATIONS are reversible by flipping a status back. The 26 CREATES are NOT -- undoing them would need a delete, and this repo has no delete path by design. The creates are additive and are exactly the records the deploy configures, so reversal is not wanted; but "every action is reversible" was wrong and is corrected here. ORDER IS LOAD-BEARING AND IS NOT AN IMPLEMENTATION DETAIL: CREATE every GUA record, VERIFY by read-back, and only THEN deprecate. Reversed, there is an interval in which the apex marks a live VIP's only record unusable -- the same orphaning hazard DEFECT 3 of the 2026-08-01 CORRECTION NOTE identified for prefixes. WHY IT DERIVES THE ULA->GUA MAP FROM THE ROLE SLUG rather than from hextet arithmetic: the ULA and GUA hextets differ per DC (dc0's metal-admin is fd50:...:220 -> 2602:f3e2:f02:20) and a transposition would be silent. Role slug is the stable key both sides share, and it comes from d139-gua-carve.py's own CARVE table, which is IMPORTED rather than retyped. If a role maps to more than one GUA /64 (provider-public owns :10 and :11) the tool REFUSES rather than picking -- an ambiguous mapping is an unrecognised state. MEASURED, not assumed (2026-08-02, live apex): the existing ULA VIP ip-addresses carry status="reserved" -- NOT "active" -- and role/dns_name/tenant/vrf/tags/custom_fields are all empty. dc-plane-apex-import.py:186,200 also creates addresses as "reserved". So the GUA records are created RESERVED, mirroring the originals, and only address + status + description carry meaning. Exit: 0 ok | 1 write/read-back error | 2 REFUSE (could not evaluate). """ import argparse import importlib.util import ipaddress import os import sys import urllib.parse _HERE = os.path.dirname(os.path.abspath(__file__)) def _load_carve(): """Import d139-gua-carve.py by path -- its hyphenated name is not importable normally. Reusing its NB client and CARVE table is deliberate: a second hand-copied table is exactly the transposition this repo keeps finding.""" p = os.path.join(_HERE, "d139-gua-carve.py") spec = importlib.util.spec_from_file_location("d139_gua_carve", p) if spec is None or spec.loader is None: print("REFUSE: cannot load %s" % p, file=sys.stderr) sys.exit(2) m = importlib.util.module_from_spec(spec) spec.loader.exec_module(m) return m C = _load_carve() die = C.die # The status the GUA VIP records are CREATED with. MEASURED from the ULA originals # (2026-08-02): they are "reserved", not "active". See module docstring. VIP_STATUS = "reserved" DEPRECATED = "deprecated" class NBW(C.NB): """The carve tool's client plus PATCH -- it never needed one, having no update path.""" def patch(self, path, body): return self._req("PATCH", path, body) def gua_net_for_role(dc, role, live_gua=None): """The GUA /64 carrying `role` for this DC, from the imported CARVE table. REFUSES on an ambiguous role rather than choosing, and -- when `live_gua` is supplied -- REFUSES unless the computed /64 ACTUALLY EXISTS in the apex. DEF-1 (adversarial review 2026-08-02, CRITICAL): computing the target arithmetically and never asking the apex whether it exists is a silent orphan-create. MEASURED: vr1-dc1's GUA carve is INCOMPLETE -- only four rows exist under 2602:f3e2:f03::/48, all provider-public, with no :20::/64 and no :21::/64 -- so `--dc vr1-dc1` planned 26 creates into prefixes that DO NOT EXIST and then deprecated dc1's only authoritative rows, at rc=0 with no warning. dc0 hid the bug because all sixteen of its targets happen to exist. The imported carve tool checks its own preconditions ("refusing to half-carve a DC"); this one checked none. """ base48 = ipaddress.ip_network(C.DC_GUA[dc]) hextets = [nn for nn, r, _lbl, _parent in C.CARVE if r == role] if not hextets: die("no D-139 GUA plane carries apex role %r -- cannot re-home its addresses" % role) if len(hextets) > 1: die("apex role %r maps to %d GUA /64s (%s) -- ambiguous, refusing to choose" % (role, len(hextets), ", ".join("%#x" % h for h in hextets))) net = C.sub_at(base48, hextets[0], 64) if live_gua is not None and str(net) not in live_gua: die("target GUA prefix %s (role %r) DOES NOT EXIST in the apex for %s. Step 1/2 " "have not carved this DC, so creating addresses inside it would orphan them. " "Run netbox/d139-gua-carve.py --dc %s --commit first." % (net, role, dc, dc)) return net def plan(dc, prefixes, addrs): """Returns (creates, dep_addrs, dep_prefixes, already). creates -- GUA ip-address payloads to POST dep_addrs -- ULA ip-address rows to mark deprecated dep_prefixes -- ULA prefix rows to mark deprecated already -- GUA addresses that already exist (idempotent re-run) """ ula48 = ipaddress.ip_network(C.RETIRED_ULA_48) gua48 = ipaddress.ip_network(C.DC_GUA[dc]) # DEF-1: the set of GUA prefixes that ACTUALLY EXIST for this DC. gua_net_for_role() # refuses against this, so a target is never computed into thin air. live_gua = {str(ipaddress.ip_network(p["prefix"])) for p in prefixes if C.scope_slug(p) == dc} # The ULA prefixes in scope: this DC's, inside the retired /48. Same selection the # carve tool's RETIRE-REPORT makes, so the two cannot disagree about scope. ula_pfx = [] for p in prefixes: if C.scope_slug(p) != dc: continue n = ipaddress.ip_network(p["prefix"]) if n.version == 6 and n.subnet_of(ula48): ula_pfx.append((n, p)) if not ula_pfx: die("no ULA prefixes in scope for %s -- nothing to do, and that is not a state this " "tool should report as success (step 1/2 may target a different apex)" % dc) existing = {str(ipaddress.ip_interface(a["address"]).ip) for a in addrs} creates, dep_addrs, already = [], [], [] for n, p in ula_pfx: if n.prefixlen != 64: continue # /60 parents hold no addresses; deprecated below role = (p.get("role") or {}).get("slug") if not role: die("ULA prefix %s has no apex role -- cannot map it to a GUA plane" % n) gua = gua_net_for_role(dc, role, live_gua) for a in addrs: ai = ipaddress.ip_interface(a["address"]) if ai.version != 6 or ai.ip not in n: continue offset = int(ai.ip) - int(n.network_address) tgt = ipaddress.ip_address(int(gua.network_address) + offset) dep_addrs.append(a) if str(tgt) in existing: already.append((str(tgt), a.get("description", ""))) else: creates.append({ "address": "%s/%d" % (tgt, gua.prefixlen), "status": VIP_STATUS, # Description kept VERBATIM: it names the service and the plane, both # still true on GUA, and the 2026-08-01 conformance audit identified # these objects BY description. Inventing new text would break that. "description": a.get("description", ""), }) # DEF-3 (adversarial review 2026-08-02, HIGH): SILENT UNDER-COUNT. Deleting or # re-scoping ONE ULA /64 prefix row yielded CREATE=13 / DEPA=13 / DEPP=8 at exit 0 -- # thirteen live VIPs neither created nor deprecated, reported as success. Same class # as DEFECT 2 of the 2026-08-01 CORRECTION NOTE (a carve that does less and exits # clean). The prefix ROW is not the authority on what exists; the ADDRESSES are. # So: every v6 address of this DC inside the retired /48 must be covered by an # in-scope /64. Any that is not is an unrecognised state, and unrecognised REFUSES # rather than being quietly skipped. # Addresses belonging to ANOTHER DC are legitimately out of scope -- the retired /48 # is shared (dc0 uses :22x, dc1 uses :32x). Scoping this check to the whole /48 was a # FALSE POSITIVE caught by running it: it flagged dc1's 26 VIPs while planning dc0. # So an address is accounted for if EITHER this DC processed it, OR some other DC's # ULA prefix row covers it. What remains -- inside the retired /48, in none of this # DC's processed /64s, and claimed by no other DC -- is the real under-count signal. # Note a /60 PARENT does not count as coverage: the reviewer's scenario was exactly a # missing /64 row whose /60 parent still existed, and treating the parent as coverage # would re-open the hole this guard closes. other_dc_ula = [] for p in prefixes: if C.scope_slug(p) == dc: continue try: n = ipaddress.ip_network(p["prefix"]) except ValueError: continue if n.version == 6 and n.subnet_of(ula48): other_dc_ula.append(n) covered = {id(a) for a in dep_addrs} orphans = [] for a in addrs: try: ai = ipaddress.ip_interface(a["address"]) except ValueError: continue if ai.version != 6 or ai.ip not in ula48: continue if id(a) in covered: continue if any(ai.ip in n for n in other_dc_ula): continue # another DC's row owns it -- not our business orphans.append(a) if orphans: die("%d ULA ip-address(es) inside %s are claimed by NO prefix row -- not by an " "in-scope /64 for %s, and not by any other DC. Their /64 row is missing, " "mis-scoped or roleless, and processing the rest would silently do less than " "step 6 requires. First: %s" % (len(orphans), ula48, dc, ", ".join(a["address"] for a in orphans[:4]))) dep_prefixes = [p for _n, p in ula_pfx if (p.get("status") or {}).get("value") != DEPRECATED] dep_addrs = [a for a in dep_addrs if (a.get("status") or {}).get("value") != DEPRECATED] return creates, dep_addrs, dep_prefixes, already def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) ap.add_argument("--dc", required=True, choices=sorted(C.DC_GUA)) ap.add_argument("--commit", action="store_true", help="apply; without it this is a DRY RUN and writes nothing") a = ap.parse_args() url, tok = os.environ.get("NETBOX_URL"), os.environ.get("NETBOX_TOKEN") if not url or not tok: die("set NETBOX_URL and NETBOX_TOKEN from the env (never argv -- it would land in " "shell history): . ~/vr1-office1-creds/vr1-netbox-sandbox.env") # DEF-2 (adversarial review 2026-08-02, CRITICAL): the apex-IDENTITY guard. It exists # in d139-gua-carve.py's main() (:159-163), and importing that module runs its # constants and classes but NEVER its main() -- so subclassing C.NB inherited the # TRANSPORT and left the SAFETY POSTURE behind. Identity is checked BEFORE any network # call, because reachability is not identity: pointing this at the v1 reference would # connect fine and write to the wrong NetBox. host = urllib.parse.urlsplit(url).hostname or "" if host not in C.SANDBOX_HOSTS: die("'%s' is not the VR1 working apex. office1-netbox (10.10.1.10) takes ALL VR1 " "reads and writes; netbox.baldurkeep.com is the v1 REFERENCE and stays " "untouched (DOCFIX-195)." % host) nb = NBW(url, tok) try: prefixes = nb.get_all("/ipam/prefixes/") addrs = nb.get_all("/ipam/ip-addresses/") except RuntimeError as e: die("apex unreachable or rejecting: %s" % e) creates, dep_addrs, dep_prefixes, already = plan(a.dc, prefixes, addrs) print("D-139 STEP 6 -- %s -- apex %s" % (a.dc, url)) print(" CREATE %d | ALREADY %d | DEPRECATE-ADDR %d | DEPRECATE-PFX %d" % (len(creates), len(already), len(dep_addrs), len(dep_prefixes))) print("\n CREATE (GUA, status=%s):" % VIP_STATUS) for c in creates: print(" %-34s %s" % (c["address"], c["description"])) if already: print("\n ALREADY PRESENT (idempotent -- left untouched):") for addr, desc in already: print(" %-34s %s" % (addr, desc)) print("\n DEPRECATE ip-addresses (ULA -- NOT deleted):") for x in dep_addrs: print(" %-34s %s" % (x["address"], x.get("description", ""))) print("\n DEPRECATE prefixes (ULA -- NOT deleted):") for x in dep_prefixes: print(" %-34s role=%s" % (x["prefix"], (x.get("role") or {}).get("slug"))) if not a.commit: print("\nDRY RUN -- nothing was written. Re-run with --commit to apply.") return 0 # ---- PHASE 1: CREATE. Nothing is deprecated until every create is read back. ---- try: for c in creates: nb.post("/ipam/ip-addresses/", c) except RuntimeError as e: print("FAIL: create: %s" % e, file=sys.stderr) print("NOTHING WAS DEPRECATED -- the ULA records are untouched and still " "authoritative. Re-run; creates are idempotent.", file=sys.stderr) return 1 # ---- PHASE 2: VERIFY BY READ-BACK, against the artifact and not the response. ---- try: back = {str(ipaddress.ip_interface(x["address"]).ip) for x in nb.get_all("/ipam/ip-addresses/")} except RuntimeError as e: die("read-back failed: %s" % e) missing = [c["address"] for c in creates if str(ipaddress.ip_interface(c["address"]).ip) not in back] if missing: print("FAIL: %d GUA address(es) not present on read-back: %s" % (len(missing), ", ".join(missing)), file=sys.stderr) print("NOTHING WAS DEPRECATED -- the ULA records remain authoritative.", file=sys.stderr) return 1 print("\n read-back OK: %d GUA VIP address(es) present" % len(creates)) # ---- PHASE 3: DEPRECATE. Only now, and never a delete. ---- try: for x in dep_addrs: nb.patch("/ipam/ip-addresses/%d/" % x["id"], {"status": DEPRECATED}) for x in dep_prefixes: nb.patch("/ipam/prefixes/%d/" % x["id"], {"status": DEPRECATED}) except RuntimeError as e: print("FAIL: deprecate: %s" % e, file=sys.stderr) print("The GUA records ARE created and verified; some ULA rows may still read " "active. Re-run -- deprecation is idempotent.", file=sys.stderr) return 1 # ---- PHASE 4: verify the deprecation landed, again on the artifact. ---- try: pfx2 = {p["id"]: p for p in nb.get_all("/ipam/prefixes/")} adr2 = {x["id"]: x for x in nb.get_all("/ipam/ip-addresses/")} except RuntimeError as e: die("post-deprecate read-back failed: %s" % e) bad = [x["address"] for x in dep_addrs if (adr2.get(x["id"], {}).get("status") or {}).get("value") != DEPRECATED] bad += [p["prefix"] for p in dep_prefixes if (pfx2.get(p["id"], {}).get("status") or {}).get("value") != DEPRECATED] if bad: print("FAIL: %d row(s) did not take status=deprecated: %s" % (len(bad), ", ".join(bad)), file=sys.stderr) return 1 print(" read-back OK: %d address(es) + %d prefix(es) now deprecated" % (len(dep_addrs), len(dep_prefixes))) print("\nSTEP 6 APPLIED. Nothing was deleted; every change is reversible by " "flipping a status back.") return 0 if __name__ == "__main__": sys.exit(main())