# NetBox imports -- v1 (IPv4-only) and VR1 DC-DC (multi-DC, dual-stack) scope

This directory contains the NetBox import scripts for both the original v1
(IPv4-only, single-site) deployment and the VR1 DC-DC (two-DC, dual-stack)
buildout. Each script is idempotent; re-running is safe.

## VR1 DC-DC scripts (2026-07-09, closes tooling gap register #3)

### `dc-dc-prefixes-import.py`

Extends the v1 single-site IPv4-only pattern to VR1's two-DC, dual-stack
model (D-101, `docs/design-decisions.md`). Per DC (`--dc dc1` or `--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 is invented.** D-101 names three literals as NetBox-assigned and
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 with no defaults --
`ORG_ULA_48`, `DC_GUA_PREFIX`, and (for `--dc dc2` only) `DC2_V4_SUPERNET`.
The script validates format/containment and FAILS LOUD if any is missing or
malformed; it never silently substitutes DC1's values for DC2 or invents a
/48. DC1's v4 planes ARE hardcoded here, deliberately -- D-101 rules DC1
inherits DC0's layout unchanged, so those six CIDRs are the ADOPTED decision
text itself, not an inferred value.

The exact per-plane subdivision of the ULA /48 and the GUA carve (which /64
within the /56/whatever goes to which plane) is this script's OWN PROPOSED
scheme -- documented in the script's module docstring -- and has NOT itself
been operator-ratified as a D-NNN sub-decision. Review it before trusting
what this script would write to a real NetBox.

```
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

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
```

**Role slugs used here are NEW** (`provider-public`/`metal-admin`/
`metal-internal`/`data-tenant`/`storage`/`replication`, matching the CURRENT
six-plane model in `scripts/lib-net.sh`) -- NOT the same slugs as
`ipv4-prefixes-import.py` below, which predates the D-052/D-053 six-plane
cutover. This staleness in the v1 script is flagged, not fixed, here (out of
scope -- that script is a v1/DC0 artifact this delivery doesn't touch).
These roles must exist in NetBox before running (create out of band; this
script does not create IPAM roles, same assumption the v1 scripts make).

**Site collision note:** DC1 may create prefixes numerically identical to
the existing `vr0-dc0` site's entries (D-101's inherit-unchanged ruling).
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 history, is an operator IPAM-hygiene
call this script does not make for you (it prints a note, does not decide).

**UNVALIDATED**: no live NetBox / `pynetbox`-reachable instance was
available this session (operator's workstation, not the vopenstack-jesse
jumphost) to run this end-to-end against a real server. Tested via
`tests/dc-dc-prefixes-import/` -- an in-memory fake NetBox client exercising
the full `main()` path for both DCs, idempotency, and every fail-loud case
(37/37 PASS) -- but a real NetBox run has not confirmed the actual API
shape/behavior.

Run order: after `ipv4-prefixes-import.py`/`ipv6-mark-reserved.py` are no
longer relevant to VR1 (they are v1/DC0-scoped), and before Stage 2/3 of
`docs/dc-dc-deployment-workflow.md` (which cite this pipeline's literals).

## v1 (IPv4-only, single-site) scripts

### `ipv4-prefixes-import.py`

Adds the IPv4 prefixes required for v1:

- Metal `/22` (10.12.8.0/22)
- Provider `/22` (10.12.4.0/22) with Provider IP Ranges (FIP pool + API VIPs)
- LBaaS Mgmt `/22` (10.12.32.0/22)
- IPv4 tenant pool `/16` (default 10.20.0.0/16; configurable via
  `TENANT_POOL_CIDR` env var)

Run order: first.

```
NETBOX_URL=https://netbox.baldurkeep.com NETBOX_TOKEN=<token> \
    python3 ipv4-prefixes-import.py
```

### `ipv6-mark-reserved.py`

Marks existing IPv6 prefixes scoped to VR0 DC0 as **reservation status** per
**D-015** (v1/v2 fork). The IPv6 entries from earlier session work are NOT
deleted -- they're preserved to document v2 design intent without implying
they are active during v1.

Run order: second (after IPv4 prefixes are in place).

```
NETBOX_URL=https://netbox.baldurkeep.com NETBOX_TOKEN=<token> \
    python3 ipv6-mark-reserved.py
```

Use `--dry-run` to preview without changes. Use `--revert` only when v2
work begins (sets IPv6 prefixes back to active).

## Deferred to v2

### VLAN imports (`vlans-import.py` -- removed)

Per the v1/v2 fork session Q2, additional VR0 DC0-VLANs group entries
(VIDs 50, 200, 220, 221, 222, 230, 260, 270) are **not imported in v1**.

Rationale: MAAS currently uses untagged-per-fabric on the existing network
layout. Modeling additional VLAN entries in NetBox without corresponding
network-side VLAN tagging would be misleading documentation. The VID 240
(OS-Provider) entry imported during prior session work is sufficient for v1
since it pairs with the Provider /22 prefix.

When v2 work begins, the VLAN import script will be re-introduced under
the v2 design with VLAN tagging actually in play.

### IPv6 active prefixes

The IPv6 prefix entries previously imported (Provider /60 + sub-/64s, Metal
/60, Data /60, Storage /60, Replication /60, LBaaS Mgmt /60, OOB /60) are
**reserved** in NetBox via `ipv6-mark-reserved.py`. They become active
again under the planned `/60 -> /64` refactor and full re-import when v2
work begins.

## NetBox version

These scripts assume NetBox 4.x:

- Prefix scope: `scope_type="dcim.site"` + `scope_id=<id>` (not legacy `site=` field)
- Prefix read: `p.scope` (not `p.site`)
- Status field: `"reserved"` / `"active"` as lowercase choice slugs

If your NetBox is older, the scripts will need adjustment.

## Sequence for v1 deploy gate

1. `python3 ipv4-prefixes-import.py` -- succeeds; verification block clean
2. `python3 ipv6-mark-reserved.py` -- succeeds; all IPv6 prefixes now reserved
3. Bundle drafting can proceed; values traced to NetBox are now authoritative