Changelog 2026-07-09 -- NetBox multi-DC/dual-stack import pipeline (DOCFIX-152)

No live infrastructure touched -- new script + test harness only. Closes tooling gap register item #3 in docs/dc-dc-deployment-workflow.md.

Item

1. DOCFIX-152 -- netbox/dc-dc-prefixes-import.py

FILES: netbox/dc-dc-prefixes-import.py (new), netbox/README.md (new VR1 section), tests/dc-dc-prefixes-import/ (new: run-tests.sh, test_logic.py, fake_pynetbox.py, stub_syspath/pynetbox.py).

WHAT: extends the v1 single-site IPv4-only NetBox import pattern (netbox/ipv4-prefixes-import.py) to VR1's two-DC, dual-stack model per D-101. Per DC (--dc dc1/--dc dc2), creates the six-plane IPv4 structure plus the D-101 family-matrix IPv6 legs (ULA for metal-admin/metal-internal/data-tenant/storage/replication, GUA for provider-public).

Nothing invented, consistent with this repo's hard rule: D-101 names three literals as NetBox-assigned, explicitly "NOT hardcoded in this decision" -- the org ULA /48, the per-DC GUA carve out of the real ARIN 2602:f3e2::/32 block, and DC2's v4 supernet. All three are REQUIRED environment variables (ORG_ULA_48, DC_GUA_PREFIX, and, for dc2 only, DC2_V4_SUPERNET) with NO defaults -- the script validates format and containment and FAILS LOUD if any is missing, malformed, out of range, or (for DC2's supernet) overlapping DC1. DC1's six v4 planes ARE hardcoded, deliberately: D-101 rules DC1 inherits DC0's layout UNCHANGED, so those CIDRs are the ADOPTED decision text itself, not an inference.

The exact per-plane subdivision of the ULA /48 and the GUA carve (which /64 goes to which plane) is this script's OWN PROPOSED scheme, documented in the module docstring as NOT itself an operator-ratified D-NNN sub-decision -- flagged for review before trusting real NetBox writes, the same posture D-102 had before its own ratification pass folded it into D-101.

FOUND AND FIXED while writing the test harness: the first draft's example GUA addresses (2602:f3e2:0:100::/40 style) had host bits set beyond the /40 boundary (the fourth hextet exceeds bit 40) -- Python's ipaddress.ip_network(..., strict=True) correctly rejected them. Corrected to 2602:f3e2:1000::/40 / 2602:f3e2:2000::/40 in both the script's own docstring examples and the test data.

Also found and fixed a real test-harness bug (not a script bug): the end-to-end test counted the substring "CREATED" in captured stdout to verify prefix-creation counts, but the script's own site-creation message also contains the word "CREATED" ('... -- CREATED.' when a new NetBox site is created), inflating the count by one on first run. Tightened the assertion to count "CREATED prefix" / "EXISTS prefix" specifically.

FLAGGED, not fixed (out of scope): netbox/ipv4-prefixes-import.py's existing IPAM role slugs (provider/metal/lbaas-management/ openstack-tenant) predate the D-052/D-053 six-plane cutover that scripts/lib-net.sh reflects. This new script uses NEW role slugs matching the CURRENT six-plane names -- a real, pre-existing staleness in the v1 script, called out in both the new script's docstring and netbox/README.md rather than silently perpetuated or silently fixed mid-step in an unrelated v1 artifact.

FLAGGED as a genuine open call, not silently decided: DC1's import may create prefixes numerically identical to the existing vr0-dc0 NetBox site's entries. NetBox permits duplicate global prefixes (soft warning, not a hard block) but whether to retire the vr0-dc0 entries once DC1 supersedes that rehearsal environment, or keep both for historical record, is an operator IPAM-hygiene decision -- the script prints a note and does not decide it.

VERIFIED, not just asserted:

• New harness tests/dc-dc-prefixes-import/: 37/37 PASS. Pure-logic tests for every validator (validate_ula_48, validate_gua_prefix, validate_dc2_supernet) and carve function (carve_dc2_v4, carve_ula, carve_gua), plus a full fake-NetBox end-to-end run of main() for both DCs covering: happy path, idempotency (re-run creates nothing, reports all EXISTS), DC2's supernet is genuinely required (fails loud when unset), and argparse's --dc requirement/choice validation. The fake NetBox client (fake_pynetbox.py) implements only the specific pynetbox calls this script makes -- not a general mock.
• bash scripts/repo-lint.sh: 0 fail, 1 documented legacy WARN. Caught and fixed a real CRLF regression during authoring: a Python-based find/replace used during test-data cleanup wrote the file back in Windows text mode (\r\n), which repo-lint's L1 check correctly flagged; fixed by rewriting the file in binary mode with LF-only line endings.
• bash scripts/run-tests-all.sh: full gauntlet 23/45 FAILED -- the SAME 23 pre-existing environment-gap failures already documented in docs/changelog-20260709-dc-selector-convention.md (jq missing on this workstation, or live juju/cloud-dependent suites); the new dc-dc-prefixes-import suite itself is clean (37/37), confirming zero regressions.

UNVALIDATED regardless of the above: no live NetBox / pynetbox-reachable instance exists this session (operator's workstation, not the vopenstack-jesse jumphost) to run this end-to-end against a real server. The fake-NetBox tests confirm the script's OWN logic is internally consistent; they cannot confirm pynetbox's real API surface matches what this script assumes (which mirrors the same assumption the existing v1 scripts already make, uncontested, in this same directory).

REVERT: rm -f netbox/dc-dc-prefixes-import.py && rm -rf tests/dc-dc-prefixes-import && git checkout HEAD~ -- netbox/README.md (safe -- no other script calls this one yet).

Next actionable step

Tooling gap register #3 CLOSED (mechanism). Before a real run: the operator must generate the org ULA /48 (RFC 4193 random allocation) and obtain the per-DC GUA carve from whoever manages 2602:f3e2::/32 region-0 /36 -- neither exists yet (this was already true; this script doesn't create that gap, it surfaces it explicitly via fail-loud env-var requirements instead of a silent default). Stage 2/3 runbooks (not yet authored) are the first real consumers of this pipeline's output.