diff --git a/docs/README-D057-PACK.md b/docs/README-D057-PACK.md new file mode 100644 index 0000000..fde799c --- /dev/null +++ b/docs/README-D057-PACK.md @@ -0,0 +1,108 @@ +# D-057 provider-vip split -- install pack + +> RENUMBERED per D-058 (2026-06-29): provider-vip=10.12.8.0/22, metal-admin=10.12.12.0/22, +> metal-internal=10.12.16.0/22, data-tenant=10.12.20.0/22, oob=10.12.60.0/22. See +> docs/D-058-renumber.md for the map, the jumphost ordering trap, and the committed-foundation +> cascade still to sweep. This pack carries the renumbered scheme and is re-validated. + +Latest versions of every file produced for the D-057 remediation (move the public +API VIP plane onto a tagged routed VLAN so the untagged provider NIC is free for OVS +br-ex, restoring floating-IP reachability). Files are laid out in repo-relative +folders -- drop them into the repo at the paths shown. + +LEGEND: [NEW] new file | [CHG] modified existing file | [DOC] documentation + +-------------------------------------------------------------------------------- +## Contents and destination paths +-------------------------------------------------------------------------------- + bundle.yaml -> bundle.yaml [CHG] + D-057 delta: 11 charms public->provider-vip; 11 VIP provider legs 10.12.4.X-> + 10.12.8.X (admin .8 / internal .12 legs unchanged); openstack0 MAC trimmed from + ovn-chassis bridge-interface-mappings; header comments updated. Nothing else. + + scripts/provider-vip-standup.sh -> scripts/provider-vip-standup.sh [NEW] + Creates the MAAS provider-vip plane (space + VID 104 on the provider fabric + + subnet 10.12.8.0/22 + gateway + reserved band). Dry-run by default; --apply to + execute. Idempotent. MTU mirrors the PROVIDER parent fabric (not metal-internal). + + scripts/carve-host-interfaces.sh -> scripts/carve-host-interfaces.sh [CHG] + Host interface carve: enp1s0 -> raw + L3-less (OVS br-ex uplink); new + enp1s0.104 -> br-prov-api (standard bridge) -> static 10.12.8.N. Dry-run default; + per-host; idempotent. + + scripts/lib-net.sh -> scripts/lib-net.sh [CHG] + Adds the shared contract: PROVIDER_VIP_CIDR=10.12.8.0/22, PROVIDER_VIP_VID=104. + Consumed by both the carve and the stand-up. + + scripts/d057-bundle-check.py -> scripts/d057-bundle-check.py [NEW] + Focused, fail-closed checker of the D-057 bundle invariants. Run as a pre-deploy + gate: `python3 scripts/d057-bundle-check.py bundle.yaml`. (Interim gate -- see + R2 in docs/D-057-REVIEW-ITEMS.md: review-bundle.py is pre-D-052 and not current.) + + tests/provider-vip-standup/ -> tests/provider-vip-standup/ [NEW] + tests/carve-host-interfaces/ -> tests/carve-host-interfaces/ [CHG] + Behavior tests (fake `maas` + real jq). Run: `bash tests//run-tests.sh`. + Harnesses self-`chmod +x` their fakebin at runtime (GitHub Desktop strips exec + bits). The standup FRESH case also guards the MTU source (asserts mtu comes from + the provider parent, not metal-internal). + + runbooks/provider-vip-maas-standup.md -> runbooks/provider-vip-maas-standup.md [DOC] + Gated manual runbook for the MAAS plane. Phase-1 audit + the virbr1 + vlan_filtering gate are uniquely useful; Phase-2 creates are superseded by the + script (noted in-file; R1). + + runbooks/jumphost-provider-vip-gateway.md-> runbooks/jumphost-provider-vip-gateway.md[DOC] + Gated runbook to set the jumphost L3 gateway (virbr1.104 = 10.12.8.1): + audit -> reversible runtime apply -> systemd-oneshot persistence (recommended) + or netplan. Deliberately a runbook, not a script (one-time, non-portable, + libvirt-persistence risk untestable by fixtures). + + docs/D-057-REVIEW-ITEMS.md -> docs/D-057-REVIEW-ITEMS.md [DOC] + End-of-deployment reconciliation log (R1-R6): runbook redundancy, stale + review-bundle.py, bundle machine-id fidelity, oob CIDR, gateway-default-route + watch-item, octavia chassis bim. + + docs/D-058-renumber.md -> docs/D-058-renumber.md [DOC] + The plane renumber: authoritative map, jumphost ordering trap, NetBox-apex note, + and the committed-foundation cascade list. Read this first if CIDRs look unfamiliar. + + docs/D-057-DECIDED-append.md -> APPEND to docs/design-decisions.md [DOC] + The D-057 decision record. Append its body to docs/design-decisions.md (do not + keep as a standalone file long-term). + +-------------------------------------------------------------------------------- +## Dependencies (NOT shipped -- already in repo / environment) +-------------------------------------------------------------------------------- + scripts/lib-hosts.sh UNCHANGED repo file. Required at runtime by + carve-host-interfaces.sh AND by the carve test harness. + Ensure it is present; this pack does not modify it. + jq on the jumphost (scripts + harnesses). + PyYAML for d057-bundle-check.py: pip install pyyaml --break-system-packages + +-------------------------------------------------------------------------------- +## CRITICAL: these changes are ATOMIC -- land them in the SAME redeploy +-------------------------------------------------------------------------------- +The carve frees enp1s0 and moves the container `public` attach to br-prov-api. If the +NEW carve/stand-up deploy against the OLD bundle (public still -> provider-public), +Juju rebuilds the Linux bridge br-enp1s0 and REPRODUCES D-057. Land together: + (1) scripts/lib-net.sh + provider-vip-standup.sh + carve-host-interfaces.sh + (2) bundle.yaml + (3) the host-nginx :81 line on the proxy VM 10.12.4.7 (Horizon VIP 10.12.4.58 -> + 10.12.8.58) -- a proxy-VM config change, not a repo file; do it in the same window. + +-------------------------------------------------------------------------------- +## Execution order (rehearsal) +-------------------------------------------------------------------------------- + 0. GATE on the jumphost: `cat /sys/class/net/virbr1/bridge/vlan_filtering` MUST be 0. + 1. PULL the committed pack to the jumphost (commit from Windows; jumphost pulls). + 2. GATE `python3 scripts/d057-bundle-check.py bundle.yaml` -> must PASS. + 3. MAAS `bash scripts/provider-vip-standup.sh` (review dry-run) then `--apply`. + then `juju reload-spaces` so Juju sees the provider-vip space. + 4. CARVE per host at MAAS-Ready: `bash scripts/carve-host-interfaces.sh ` + (dry-run) then apply. (Exact invocation per the carve's own usage.) + 5. DEPLOY the bundle (atomic partner of steps 3-4) + the host-nginx :81 change. + 6. GW run runbooks/jumphost-provider-vip-gateway.md (set virbr1.104 = 10.12.8.1). + 7. VALIDATE D-011 (FIP reachability; resume phase-06 Step 6.3). + +Tests can be run any time, offline: `bash tests/provider-vip-standup/run-tests.sh` +and `bash tests/carve-host-interfaces/run-tests.sh` (both expect ALL PASS).