#!/usr/bin/env python3
"""
NetBox multi-DC / dual-stack prefix import for VR1 DC-DC (Omega Cloud).
Closes tooling gap register item #3 in docs/dc-dc-deployment-workflow.md:
extends the v1 (netbox/ipv4-prefixes-import.py) single-site IPv4-only import
to the VR1 two-DC, dual-stack model ratified in D-101 (docs/design-decisions.md).
Per DC (dc1 or dc2, selected via --dc, mirroring the scripts/lib-net.sh
$DC selector convention, DOCFIX-151), creates the six-plane structure with
the D-101 family matrix:
Plane v4 v6 family
provider-public (see below) GUA (dual-stack)
metal-admin (see below) ULA (dual-stack, 2026-07-09 amendment)
metal-internal (see below) ULA (dual-stack)
data-tenant (see below) ULA-only
storage (see below) ULA-only
replication (see below) ULA-only
DC1 v4: INHERITS the DC0 six-plane CIDRs unchanged (D-101 -- "DC1 equals the
validated template"), i.e. the SAME literals as netbox/ipv4-prefixes-import.py,
hardcoded here for that reason (this is not an inferred value; it is the
explicit text of an ADOPTED decision). Scoped to a DISTINCT NetBox site
(vr1-dc1), not the existing vr0-dc0 site.
DC2 v4: D-101 explicitly states DC2's supernet is "NetBox-assigned... not
hardcoded." No default is provided here -- DC2_V4_SUPERNET is a REQUIRED
environment variable with no fallback. Running with --dc dc2 and no
DC2_V4_SUPERNET set FAILS LOUD rather than guessing or reusing DC1's range.
IPv6 (both DCs): D-101 names two literals as NetBox-assigned and "NOT
hardcoded in this decision": the org ULA /48, and the per-DC GUA carve out
of the already-real ARIN 2602:f3e2::/32 region-0 /36 (the /32 itself IS a
real literal quoted in D-101's own text -- only its per-DC subdivision is
still open). Both are REQUIRED environment variables with no defaults:
ORG_ULA_48 and DC_GUA_PREFIX.
IMPORTANT -- what this script does NOT do: it does not invent the org ULA
/48 or the GUA carve. The operator must generate/obtain those (an RFC 4193
random ULA /48, and the actual per-DC GUA assignment from whoever manages
2602:f3e2::/32) and pass them in. This script only validates their FORMAT
and then applies a DETERMINISTIC, DOCUMENTED SUBDIVISION into per-plane
prefixes (see SUBCARVE SCHEME below). That subdivision scheme is this
script's own proposal -- it is NOT itself a ratified D-NNN sub-decision.
Review it before trusting the values this script would write to a real
NetBox. (Precedent: D-102's MTU sub-policy was folded into D-101 only after
explicit operator ratification; this carve scheme has not had that pass.)
SUBCARVE SCHEME (proposed, unratified -- review before real use):
- ULA: each DC gets a /56 out of the org /48 (dc1 = ::0/56, dc2 = ::1:00/56,
i.e. the 8 bits immediately after the /48 index the DC -- room for up to
256 DCs, far beyond VR1's two). Within a DC's /56, each of the three
ULA-family planes (data-tenant, storage, replication) plus the two
dual-stack planes' ULA leg (metal-admin, metal-internal) gets a /64,
indexed in the fixed plane order below (provider-public has no ULA leg,
so its index is skipped -- the /64 offsets are NOT contiguous with the
plane list index, they are assigned only to the five ULA-bearing planes).
- GUA: each DC's already-carved GUA prefix (DC_GUA_PREFIX, e.g. a /40 or
/44 -- length is read from what's actually passed in, not assumed) is
subdivided the same way: provider-public gets the whole thing as a
single /64 (VR1 has no other GUA-bearing plane in the matrix above;
tenant-facing GUA delegation is a separate, later, per-tenant carve out
of this same block -- not this script's job, see netbox/README.md).
Idempotent: re-running is safe (existing prefixes are detected and skipped
unless --update). NetBox version: 4.x (scope_type/scope_id, not legacy site=).
Usage:
# DC1 (v4 inherited, only v6 top-level blocks required):
NETBOX_URL=https://netbox.baldurkeep.com NETBOX_TOKEN=<token> \\
ORG_ULA_48=fd00:1234:5678::/48 DC_GUA_PREFIX=2602:f3e2:1000::/40 \\
python3 dc-dc-prefixes-import.py --dc dc1
# DC2 (v4 supernet ALSO required, nothing defaulted):
NETBOX_URL=... NETBOX_TOKEN=... \\
ORG_ULA_48=fd00:1234:5678::/48 DC_GUA_PREFIX=2602:f3e2:2000::/40 \\
DC2_V4_SUPERNET=10.13.0.0/19 \\
python3 dc-dc-prefixes-import.py --dc dc2
# Preview only, no writes:
... python3 dc-dc-prefixes-import.py --dc dc1 --verify-only
KNOWN PRE-EXISTING STALENESS (flagged, not fixed here): netbox/ipv4-prefixes-
import.py's role slugs (provider/metal/lbaas-management/openstack-tenant)
predate the D-052/D-053 six-plane cutover that scripts/lib-net.sh reflects.
This script uses NEW role slugs matching the CURRENT six-plane names
(provider-public/metal-admin/metal-internal/data-tenant/storage/replication)
since VR1 is being built against the current model, not the v1-era one.
These roles must exist in NetBox before running (create out of band, same
assumption netbox/ipv4-prefixes-import.py already makes for its own roles --
this script does not create IPAM roles, only prefixes/sites use them).
UNVALIDATED: no NETBOX_URL/live NetBox and no `pynetbox`-reachable instance
were available this session (workstation, not the vopenstack-jesse jumphost)
to run this end-to-end. Reviewed against the pynetbox API shape used
successfully by the existing v1 scripts in this same directory, not executed.
"""
from __future__ import annotations
import argparse
import ipaddress
import os
import sys
try:
import pynetbox
except ImportError:
sys.stderr.write("ERROR: pynetbox not installed. pip install pynetbox\n")
sys.exit(1)
# -----------------------------------------------------------------------------
# DC1/DC2 site identity. Slugs are new -- no prior convention existed in this
# repo (grepped opentofu/*.tf and the buildout design; none found) -- chosen
# to match the D-106 Designate naming already ratified (dc1/dc2, vr1 label).
# -----------------------------------------------------------------------------
SITES = {
"dc1": {"slug": "vr1-dc1", "name": "VR1 DC1"},
"dc2": {"slug": "vr1-dc2", "name": "VR1 DC2"},
}
# Fixed plane order -- must match scripts/lib-net.sh's PLANE_NAME exactly
# (CIDR-keyed there; name-keyed here, same six planes, same order).
PLANE_ORDER = [
"provider-public",
"metal-admin",
"metal-internal",
"data-tenant",
"storage",
"replication",
]
# D-101 family matrix: which v6 family (if any) each plane carries.
# "gua" = dual-stack v4+GUA; "ula" = dual-stack v4+ULA; "ula-only" = no v4
# plane object created for the v6 leg (data-tenant/storage/replication ARE
# dual-stack-capable per D-102's Phase-A rollback posture text, but the
# ADOPTED default is IPv6-only for those three -- see D-101/D-102 body).
PLANE_V6_FAMILY = {
"provider-public": "gua",
"metal-admin": "ula",
"metal-internal": "ula",
"data-tenant": "ula-only",
"storage": "ula-only",
"replication": "ula-only",
}
# DC1 v4: the DC0 six-plane CIDRs, UNCHANGED, per D-101 ("DC1 equals the
# validated template"). Identical to netbox/ipv4-prefixes-import.py's
# historical single-plane set is NOT the comparison here -- these are the
# CURRENT six-plane values from scripts/lib-net.sh's PLANE_CIDRS, which is
# this repo's single source of truth for that layout.
DC1_V4_PREFIXES = {
"provider-public": "10.12.4.0/22",
"metal-admin": "10.12.8.0/22",
"metal-internal": "10.12.12.0/22",
"data-tenant": "10.12.16.0/22",
"storage": "10.12.32.0/22",
"replication": "10.12.36.0/22",
}
# DC2 v4: NO default. Must come from DC2_V4_SUPERNET (env var), carved into
# six sequential /22s in PLANE_ORDER, exactly mirroring DC1's /22-per-plane
# structure. The supernet must be large enough to hold six non-overlapping
# /22s (a /19 holds exactly eight /22s -- six used, two spare; anything
# smaller than /19 FAILS LOUD).
DC2_MIN_SUPERNET_PREFIXLEN = 19 # a /19 = exactly 8x /22, room for the six planes
def die(msg: str, code: int = 1) -> None:
sys.stderr.write(f"ERROR: {msg}\n")
sys.exit(code)
def get_nb() -> "pynetbox.api":
url = os.environ.get("NETBOX_URL")
token = os.environ.get("NETBOX_TOKEN")
if not url:
die("NETBOX_URL environment variable not set")
if not token:
die("NETBOX_TOKEN environment variable not set")
nb = pynetbox.api(url, token=token)
try:
_ = nb.status()
except Exception as exc: # noqa: BLE001
die(f"Could not reach NetBox at {url}: {exc}")
return nb
def find_or_create_site(nb, slug: str, name: str):
site = nb.dcim.sites.get(slug=slug)
if site is not None:
return site, False
# Minimal site record -- status defaults to NetBox's own default (active).
created = nb.dcim.sites.create(name=name, slug=slug)
return created, True
def find_role(nb, slug: str):
role = nb.ipam.roles.get(slug=slug)
if role is None:
die(
f"IPAM role with slug '{slug}' not found in NetBox. Create it first "
f"(out of band) -- this script does not create roles, matching "
f"netbox/ipv4-prefixes-import.py's existing assumption."
)
return role
# -----------------------------------------------------------------------------
# Required-literal validation. Each of these dies with a specific, actionable
# message rather than silently defaulting -- the whole point of this pipeline
# closing gap #3 is that these values are NOT invented here.
# -----------------------------------------------------------------------------
def require_env(name: str, why: str) -> str:
val = os.environ.get(name)
if not val:
die(f"{name} environment variable is required and not set -- {why}")
return val
def validate_ula_48(cidr: str) -> ipaddress.IPv6Network:
try:
net = ipaddress.ip_network(cidr, strict=True)
except ValueError as exc:
die(f"ORG_ULA_48='{cidr}' is not a valid CIDR: {exc}")
if net.version != 6:
die(f"ORG_ULA_48='{cidr}' is not an IPv6 prefix")
if net.prefixlen != 48:
die(f"ORG_ULA_48='{cidr}' must be a /48 (got /{net.prefixlen})")
# RFC 4193 ULA range is fc00::/7; the locally-assigned form sets the L bit
# (fd00::/8). Reject anything outside fc00::/7 -- a GUA or other range
# here would be a real misconfiguration, not a style nit.
if not net.subnet_of(ipaddress.ip_network("fc00::/7")):
die(f"ORG_ULA_48='{cidr}' is not within the ULA range fc00::/7 (RFC 4193)")
return net
def validate_gua_prefix(cidr: str) -> ipaddress.IPv6Network:
try:
net = ipaddress.ip_network(cidr, strict=True)
except ValueError as exc:
die(f"DC_GUA_PREFIX='{cidr}' is not a valid CIDR: {exc}")
if net.version != 6:
die(f"DC_GUA_PREFIX='{cidr}' is not an IPv6 prefix")
parent = ipaddress.ip_network("2602:f3e2::/32")
if not net.subnet_of(parent):
die(
f"DC_GUA_PREFIX='{cidr}' is not within the D-101-cited ARIN block "
f"{parent} -- if this is a genuinely different GUA allocation, "
f"that is itself a design-decision-worthy change (grep D-101 "
f"first), not something this script should silently accept."
)
if net.prefixlen >= 64:
die(f"DC_GUA_PREFIX='{cidr}' must be shorter than /64 (need room to carve a /64 for provider-public)")
return net
def validate_dc2_supernet(cidr: str) -> ipaddress.IPv4Network:
try:
net = ipaddress.ip_network(cidr, strict=True)
except ValueError as exc:
die(f"DC2_V4_SUPERNET='{cidr}' is not a valid CIDR: {exc}")
if net.version != 4:
die(f"DC2_V4_SUPERNET='{cidr}' is not an IPv4 prefix")
if net.prefixlen > DC2_MIN_SUPERNET_PREFIXLEN:
die(
f"DC2_V4_SUPERNET='{cidr}' (/{net.prefixlen}) is too small to hold "
f"six /22 planes -- need at least a /{DC2_MIN_SUPERNET_PREFIXLEN}"
)
dc1_nets = [ipaddress.ip_network(c) for c in DC1_V4_PREFIXES.values()]
for d1 in dc1_nets:
if net.overlaps(d1):
die(
f"DC2_V4_SUPERNET='{cidr}' overlaps DC1's inherited range {d1} -- "
f"D-101 requires DC2 to be non-overlapping. Choose a different supernet."
)
return net
def carve_dc2_v4(supernet: ipaddress.IPv4Network) -> dict:
subnets = list(supernet.subnets(new_prefix=22))
if len(subnets) < len(PLANE_ORDER):
die(
f"DC2_V4_SUPERNET yields only {len(subnets)} /22 subnet(s), "
f"need {len(PLANE_ORDER)}"
)
return {plane: str(subnets[i]) for i, plane in enumerate(PLANE_ORDER)}
def carve_ula(org_ula_48: ipaddress.IPv6Network, dc: str) -> dict:
dc_index = 0 if dc == "dc1" else 1
# /48 -> per-DC /56 (8-bit DC index). See SUBCARVE SCHEME in module docstring.
dc_56_candidates = list(org_ula_48.subnets(new_prefix=56))
dc_56 = dc_56_candidates[dc_index]
ula_planes = [p for p in PLANE_ORDER if PLANE_V6_FAMILY[p] in ("ula", "ula-only")]
dc_64_candidates = list(dc_56.subnets(new_prefix=64))
return {plane: str(dc_64_candidates[i]) for i, plane in enumerate(ula_planes)}
def carve_gua(dc_gua_prefix: ipaddress.IPv6Network) -> dict:
# Only provider-public carries GUA in the current family matrix.
gua_64_candidates = list(dc_gua_prefix.subnets(new_prefix=64))
return {"provider-public": str(gua_64_candidates[0])}
# -----------------------------------------------------------------------------
# NetBox writes
# -----------------------------------------------------------------------------
def create_or_report_prefix(nb, cidr: str, role_slug: str, site, description: str, update: bool) -> None:
role = find_role(nb, role_slug)
existing = nb.ipam.prefixes.get(prefix=cidr)
payload = {
"prefix": cidr,
"role": role.id,
"description": description,
"scope_type": "dcim.site",
"scope_id": site.id,
}
if existing is None:
created = nb.ipam.prefixes.create(**payload)
print(f" CREATED prefix {cidr} (id={created.id}) role={role_slug}")
elif update:
existing.update(payload)
print(f" UPDATED prefix {cidr} (id={existing.id}) role={role_slug}")
else:
print(f" EXISTS prefix {cidr} (id={existing.id}) -- skipped (use --update to overwrite)")
def verify(nb, site, v4: dict, v6_ula: dict, v6_gua: dict) -> None:
print()
print("=" * 72)
print(f"Verification -- final state for site {site.name} (id={site.id})")
print("=" * 72)
print("\nIPv4 (per plane):")
for plane in PLANE_ORDER:
cidr = v4[plane]
p = nb.ipam.prefixes.get(prefix=cidr)
status = "MISSING" if p is None else f"OK (id={p.id})"
print(f" {plane.ljust(16)} {cidr.ljust(18)} {status}")
print("\nIPv6 ULA (per plane, where applicable):")
for plane, cidr in v6_ula.items():
p = nb.ipam.prefixes.get(prefix=cidr)
status = "MISSING" if p is None else f"OK (id={p.id})"
print(f" {plane.ljust(16)} {cidr.ljust(24)} {status}")
print("\nIPv6 GUA (per plane, where applicable):")
for plane, cidr in v6_gua.items():
p = nb.ipam.prefixes.get(prefix=cidr)
status = "MISSING" if p is None else f"OK (id={p.id})"
print(f" {plane.ljust(16)} {cidr.ljust(24)} {status}")
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__.split("\n\n", 1)[0])
parser.add_argument("--dc", required=True, choices=["dc1", "dc2"], help="Which DC to import (no default -- explicit, measured selection per the $DC convention)")
parser.add_argument("--update", action="store_true", help="Update existing prefixes in place")
parser.add_argument("--verify-only", action="store_true", help="Skip writes; only print verification block")
args = parser.parse_args()
dc = args.dc
site_cfg = SITES[dc]
org_ula_48 = validate_ula_48(require_env("ORG_ULA_48", "D-101's org ULA /48 -- not defaulted, must be a real RFC 4193 /48 you generated"))
dc_gua_prefix = validate_gua_prefix(require_env("DC_GUA_PREFIX", f"the {dc} carve out of ARIN 2602:f3e2::/32 region-0 /36 cited in D-101 -- not defaulted"))
if dc == "dc1":
v4 = dict(DC1_V4_PREFIXES)
else:
dc2_supernet = validate_dc2_supernet(require_env("DC2_V4_SUPERNET", "D-101 explicitly requires DC2's v4 supernet be NetBox-assigned, not hardcoded"))
v4 = carve_dc2_v4(dc2_supernet)
v6_ula = carve_ula(org_ula_48, dc)
v6_gua = carve_gua(dc_gua_prefix)
nb = get_nb()
site, site_created = find_or_create_site(nb, site_cfg["slug"], site_cfg["name"])
print(f"Connected. Site '{site_cfg['name']}' (id={site.id}){' -- CREATED' if site_created else ''}.")
if dc == "dc1":
print(
"\nNOTE: this may create prefixes identical to the existing 'vr0-dc0' "
"site's entries (D-101: DC1 inherits DC0's v4 layout unchanged). "
"NetBox permits duplicate global prefixes (soft-warn, not a hard "
"block) but this is a real IPAM-hygiene decision for the operator: "
"either retire/delete the vr0-dc0 entries once DC1 supersedes that "
"rehearsal environment, or knowingly keep both for historical "
"record. This script does not decide that for you."
)
if not args.verify_only:
print("\nIPv4 prefixes:")
for plane in PLANE_ORDER:
create_or_report_prefix(
nb, v4[plane], plane, site,
f"VR1 {dc.upper()} {plane} (v4; D-101)", args.update,
)
print("\nIPv6 ULA prefixes:")
for plane, cidr in v6_ula.items():
create_or_report_prefix(
nb, cidr, plane, site,
f"VR1 {dc.upper()} {plane} (ULA leg; D-101, proposed subcarve -- see script docstring)",
args.update,
)
print("\nIPv6 GUA prefixes:")
for plane, cidr in v6_gua.items():
create_or_report_prefix(
nb, cidr, plane, site,
f"VR1 {dc.upper()} {plane} (GUA leg; D-101, proposed subcarve -- see script docstring)",
args.update,
)
verify(nb, site, v4, v6_ula, v6_gua)
print("\nDone.")
return 0
if __name__ == "__main__":
sys.exit(main())
