Tenant CIDR overlap correction -- work order / change plan

Status: DRAFT for the Code (jumphost) stream + operator ruling. Authored by the main-chat stream at repo HEAD 59a7c73 (2026-07-06). Read-only analysis; no live mutation and no committed-surface edit performed by main-chat.

Proposes: decision D-074 (PROPOSED; amends D-016). D-074 is next-free per bash scripts/ledger-scan.sh at this HEAD. NOTE: D-073 and DOCFIX up to 105 were consumed the same day by the jumphost stream -- Code must re-run the scan and re-confirm next-free before inserting the decision header. Do not hand-type it.

1. Finding (what is actually wrong)

The stage-4 tenant CIDR guard in scripts/tenant-onboard.sh over-enforces relative to the onboarding contract it is supposed to implement, and separately has an overlap-detection hardening gap.

• Contract intent (docs/tenant-onboarding-contract.md sec. 3, item 4): a tenant CIDR must be RFC1918 and non-colliding with (a) our allocations and (b) the client's own on-prem/VPN ranges they may later interconnect. The contract does not require non-collision with other tenants.
• Guard behaviour (tenant-onboard.sh stage 4 -- the grep -qw "$TENANT_CIDR" check run under admin_env against a cloud-wide openstack subnet list): it dies on any exact subnet-string match cloud-wide, which includes other tenants' subnets. So it forbids tenant-vs-tenant exact overlap that the contract never intended to forbid.
• Independent hardening gap: the guard is exact-string (grep -qw), so it MISSES partial/containing overlaps (e.g. a requested 10.20.20.128/25 against an existing 10.20.20.0/24). It is therefore simultaneously too strict on exact tenant matches and too loose on partial overlaps against ranges we must actually protect.

Origin of the uniqueness behaviour (and a correction of the record): it is an IPAM artifact of D-016, which models a single 10.20.0.0/16 tenant pool and carves non-overlapping /24s from it. It is not a dataplane requirement. An earlier main-chat claim that the uniqueness rule was needed for "CAPI/Magnum reachability" was wrong and is retracted here: per D-035, capi-mgmt-v2 is single-homed on its own 10.20.0.0/24 and reaches workload clusters via their API-LB floating IPs and OpenStack via the API VIPs -- it never routes into other tenants' 10.20.x space, so overlapping tenant CIDRs cannot touch the management path.

2. Proposed decision -- D-074 (PROPOSED; amends D-016)

Tenant private (overlay) CIDRs are tenant-chosen and MAY overlap across tenants. Non-collision is enforced only against a reserved-ranges registry (operator/infra allocations, section 3). NetBox (the IPAM apex) tracks the reserved/routed space; tenant overlay space leaves NetBox uniqueness tracking.

Rationale: this aligns the implementation with the onboarding contract's already-stated intent, and with the hard-isolation (SCS Domain Manager) persona. Overlap-allowed tenant CIDRs is the standard isolated-multi-tenant model -- it is why Neutron ships allow_overlapping_ips=true by default and why public-cloud VPCs let tenants pick arbitrary RFC1918. Globally-unique-per-tenant is the enterprise-private-cloud pattern (shared routed fabric, interoperating internal units), which is the opposite of what this cloud is.

Forward-only: existing tenants are not re-CIDR'd (northwind stays 10.20.20.0/24; design-decisions forbids transient-overlap re-CIDR).

PROPOSED means the operator has not ruled. Nothing in sections 3-4 is implemented until D-074 is ADOPTED.

3. Reserved-ranges registry (the ONLY thing the guard rejects)

Non-collision is enforced against these, using real subnet-overlap math (containment in either direction), not string equality:

These values were read from docs/maas-as-built-reference.md by main-chat. Code MUST re-derive them from the authoritative live/modeled source (pre-flight PLANE_CIDRS / scripts/lib-net.sh / NetBox) before wiring the guard -- do not hardcode from this doc (hard rules 2 and 3: dynamic lookup, no inferred values). Centralize the list in lib-net.sh keyed by plane name, not as scattered literals.

4. Gated correction procedure (harness-first; each phase gates the next)

Phase 0 -- read-only verification (MUST pass before any mutation)

• 0.1 Confirm allow_overlapping_ips. Read it live (juju config neutron-api ... or neutron.conf on a unit). If it is false, STOP -- flipping it is a wider blast radius that needs its own ruling; do not proceed on the assumption it is true.
• 0.2 Overlap+Magnum proof on a FOIL tenant. Onboard a foil tenant with a CIDR that deliberately overlaps an existing tenant's /24; confirm (a) the subnet creates and (b) a Magnum cluster reaches ACTIVE with a working API-LB. Capture evidence to ~/openstack-baseline/. (This foil doubles as the d011-05 P3 isolation foil.)

Phase 1 -- guard change (Code's lane; Code owns tenant-onboard.sh)

• Replace the exact-string cloud-wide guard with subnet-overlap math (Python ipaddress) against the reserved-ranges registry only. Drop the tenant-vs-tenant check.
• Extend tests/tenant-onboard/ with fixtures covering: exact tenant-vs-tenant overlap (now ALLOWED), partial overlap against a reserved range (REJECTED), exact match against a reserved range (REJECTED), and a disjoint range (ALLOWED). No script change ships without its harness.
• bash scripts/repo-lint.sh + the harness green before commit.

Phase 2 -- doc alignment

• tenant-onboarding-contract.md sec. 3.4: make explicit that tenant-vs-tenant overlap is permitted (the wording is already close; remove any implication of cloud-wide uniqueness).
• Amend D-016 with a forward-pointer to D-074.
• runbooks/tenant-onboarding-runbook.md: replace the "carve a non-colliding /24 from 10.20.0.0/16" guidance with "tenant CIDR is client-choice or the standard default; only reserved ranges are rejected."
• clientdocs/ intake field: reword "requested internal IP address" -> "requested internal network range (CIDR) -- optional; overlap-safe; default per policy" (also fixes the IP-vs-range wording mismatch).

Phase 3 -- create the devops tenant on the corrected cloud

• bash scripts/tenant-onboard.sh <devops-client> with TENANT_CIDR per the default policy ruled in section 6. Verify with scripts/tenant-assert.sh.

5. Lose / gain

Gain: implementation matches the contract and the hard-isolation persona; onboarding drops the "find a free /24" step; the intake field goes optional; clients can align to their own on-prem/VPN ranges; NetBox's uniqueness job shrinks to the routed space that genuinely must be unique (cleaner, and no global per-tenant IPAM registry to maintain across DCs for Roosevelt); the 256-/24 ceiling of one /16 stops being a scaling limit.

Lose / cost: debuggability -- an IP no longer uniquely identifies a tenant, so captures/triage need net+tenant context (mitigate with disciplined naming); no tenant-private-IP routing between tenants (an anti-pattern under hard isolation anyway); IPAM discipline narrows to reserved ranges rather than disappearing; the guard change touches a file Code is actively editing (coordination cost); D-016's /16 pool becomes vestigial (not reclaimed, just no longer enforced forward).

6. Open operator decisions (nothing proceeds until ruled)

1. Rule D-074 -- adopt the overlap-allowed model?
2. Default tenant CIDR policy -- (a) uniform default (e.g. 10.0.0.0/24) for all, or (b) client-choice with a fallback default. Recommend (b). This sets what the devops tenant receives.
3. Keep capi-mgmt 10.20.0.0/24 reserved? Recommend YES.
4. allow_overlapping_ips confirmed true? (Phase 0.1 gates everything.)

7. Coordination / lane notes

• The jumphost stream is actively editing tenant-onboard.sh and the contract today (changelog addenda 21 / 23 / 26). The Phase-1 guard edit and all live steps are the jumphost stream's lane; main-chat authored this plan only. Code: pull and read this before resuming onboard-script work.
• D-074 is next-free per the scan at HEAD 59a7c73; re-confirm before inserting.
• This is a new file with no edits to any shared/fenced file, to minimize collision.