# Changelog 2026-07-09 -- Stage 5 runbook: Juju controller + bundle, per DC (DOCFIX-156)

No live infrastructure touched -- new runbook document only. Authored
directly (not delegated), since this is the ground-truth/copy-point stage
(`docs/dc-dc-buildout-design.md` line 12: this whole repo was seeded from
`openstack-caracal-ipv4` specifically so `bundle.yaml` and `phase-01..08`
could be reused here) and the most consequential adaptation to get right.

## Item

### 1. DOCFIX-156 -- `runbooks/dc-dc-phase4-juju-bundle-per-dc.md`
FILES: `runbooks/dc-dc-phase4-juju-bundle-per-dc.md` (new), `docs/dc-dc-
deployment-workflow.md` (Stage 5 row updated).

WHAT: does NOT duplicate `phase-01..08`'s command-level content. Describes
what changes to run that existing, validated deploy loop TWICE (once per
DC): a dedicated per-DC single-unit Juju controller bootstrap (D-104), the
existing bundle deploy/vault-bringup/core-verify/network-carve/octavia
sequence referenced by filename, and the D-109 independent-per-DC-Vault-
root implication (separate `vault operator init` runs, separate unseal
shares/root tokens, stored separately per DC).

**DC1 needs literally NO VIP/CIDR changes** -- D-101 inherits DC0's layout
unchanged, so the existing `bundle.yaml` deploys into DC1's own Juju model
verbatim. **DC2 is explicitly blocked** on the same still-unassigned NetBox
literals as Stages 3/4 (gap #3's data half) -- the runbook states plainly
that DC2's octavia SAN IP, VIP band, and everything else address-derived
cannot be decided until those literals exist, and instructs stopping there
for DC2 rather than inventing a "test range."

**Every `phase-01..08` command block that reads `scripts/lib-net.sh`/
`lib-hosts.sh` values must be preceded by an explicit `lib_net_select_dc
"$DC"` / `lib_hosts_select_dc "$DC"` call (DOCFIX-151)** -- the runbook
calls out that for DC1 both are a documented no-op (so skipping them
"happens to work" by accident) while for DC2 skipping them would silently
reuse DC1's values, exactly the bug the selector convention exists to
prevent. This is the stage tooling gap register item #1 was built to
unblock, and this is the first runbook to actually exercise it.

**Two real, unresolved design gaps surfaced rather than papered over:**
1. **The D-101 IPv6 family-matrix overlay does not exist.** Which planes
   need ULA-only vs. dual-stack vs. GUA addressing is fully specified by
   D-101 (Section 2 of the buildout design), but the actual Juju charm
   config option names needed to configure that per application (`ceph-
   mon`, `ovn-central`, `octavia`, etc.) have not been confirmed against
   any charm's real current schema this session. Rather than inventing
   plausible-looking option names, Step 6 names this as blocking work with
   a three-part path to close it (confirm real charm options -> author the
   overlay -> apply it) and explicitly forbids fabricating option names.
2. **D-109's IPv6-SAN cert-issuance requirement is an unverified charm-
   behavior assumption** -- whether the vault/certificates-relation charms
   in `bundle.yaml` actually support issuing v6 SANs today has not been
   confirmed; flagged as a real finding to log if it turns out they don't,
   not something to silently route around.

Also documents the metal-admin ULA amendment explicitly (the 2026-07-09
operator ruling reversing D-101's own original v4-only lean for that
plane), warning against assuming older documentation/training-data
patterns.

VERIFIED: `bash scripts/repo-lint.sh` 0 fail, 1 documented legacy warn.
NOT YET EXECUTED.

REVERT: `rm runbooks/dc-dc-phase4-juju-bundle-per-dc.md && git checkout
HEAD~ -- docs/dc-dc-deployment-workflow.md` (safe).

## Next actionable step

The Step 6 IPv6 overlay design gap is the single biggest piece of real,
undone work surfaced by tonight's runbook-authoring pass -- it blocks this
stage's own "Ceph-over-v6 and geneve-over-v6 verified" gate criterion and
should be logged as its own tooling-gap-register item in the final
consolidation pass, alongside gaps #1-#11 already tracked.