Changelog 2026-07-10 -- $DC parameterization for the 3 MAAS scripts (DOCFIX-166)

No live infrastructure touched -- script + test-harness changes only (prep session; no jumphost/juju/MAAS access this session). Closes the CLI-wiring half of tooling gap register item #15 sub-item 2 in docs/dc-dc-deployment-workflow.md (full detail in runbooks/dc-dc-phase3-maas-enlist-deploy.md's "Known gaps" section, item 2), which blocked scripts/reenroll-hosts.sh, scripts/carve-host- interfaces.sh, and scripts/phase-00-maas-standup.sh from being invoked with a $DC argument at all -- DOCFIX-151 (2026-07-09) only gave the selector functions to lib-net.sh/lib-hosts.sh; no consumer script called them yet.

Item

1. DOCFIX-166 -- $DC env var wiring in the 3 MAAS scripts

FILES: scripts/reenroll-hosts.sh, scripts/carve-host-interfaces.sh, scripts/phase-00-maas-standup.sh, tests/carve-host-interfaces/run- tests.sh, tests/phase-00-maas-standup/run-tests.sh, new tests/reenroll- hosts/run-tests.sh.

WHAT: each script now reads an opt-in $DC env var immediately after sourcing lib-net.sh/lib-hosts.sh (the earliest possible point, matching the pattern runbooks/dc-dc-phase3-maas-enlist-deploy.md's Step 1 already documents) and, only if $DC is non-empty, calls lib_net_select_dc "$DC" (all three scripts) and lib_hosts_select_dc "$DC" (reenroll-hosts.sh and carve-host-interfaces.sh only -- phase-00-maas-standup.sh never sources lib-hosts.sh, it has no host-identity dependency to select). This matches the convention the selector functions and the Stage 4 runbook already established (an explicit $DC env var passed positionally into each function), rather than inventing a new --dc CLI-flag convention that does not exist anywhere else in this repo.

DC="${DC:-}"
if [ -n "$DC" ]; then
  lib_net_select_dc "$DC"
  lib_hosts_select_dc "$DC"     # reenroll-hosts.sh / carve-host-interfaces.sh only
fi

Backward compatible by construction: unset $DC skips the if body entirely, so every existing invocation (bash scripts/reenroll-hosts.sh --check, bash scripts/carve-host-interfaces.sh openstack0 --apply, bash scripts/phase-00-maas-standup.sh) runs byte-for-byte as it did before this change -- confirmed by re-invoking each script with no $DC set and diffing against pre-change behavior descriptions in runbooks/phase-00-teardown- maas-reset.md (see VERIFIED below).

No second validation layer was added: because all three scripts already run under set -euo pipefail, a selector function returning non-zero (dc2 at the network layer; dc1 AND dc2 at the host layer) causes the script to exit immediately with that same exit code -- which happens to line up with each script's own "1 = fatal" convention, so the propagation is free.

VERIFIED (this workstation; no jq installed, no live jumphost/MAAS/juju access -- same environment gap DOCFIX-151's changelog documented):

• Manual, jq-independent invocation of all three scripts confirms the exact intended matrix (the selector calls happen before need_jq/any MAAS call, so these do not need jq or a fake maas at all):
  • DC unset -> unaffected (rc identical to before this change in every script).
  • DC=dc0 -> explicit no-op, byte-for-byte same as unset.
  • DC=dc1 -> reenroll-hosts.sh and carve-host-interfaces.sh FAIL LOUD at lib_hosts_select_dc ("no enrolled hosts yet..."), before touching MAAS; phase-00-maas-standup.sh (network-selector only) no-ops (D-101: dc1 inherits dc0's plane literals) and proceeds to its own MAAS calls.
  • DC=dc2 -> all three FAIL LOUD at lib_net_select_dc first ("no assigned network literals yet..."), before lib_hosts_select_dc is ever reached in the two scripts that also call it.
  • DC=bogus -> all three FAIL LOUD ("unknown DC 'bogus'").
• bash scripts/repo-lint.sh: 0 fail, 1 documented legacy WARN (unchanged).
• bash scripts/run-tests-all.sh: new reenroll-hosts suite added (none existed before); it reports FAIL: jq required, identically to its sibling suites carve-host-interfaces and phase-00-maas-standup (both already jq-gated, unrelated to this change) and to roughly twenty other suites in the same gauntlet run that all fail for the same reason on this jq-less Windows workstation. Did NOT run a git stash A/B comparison this time (unlike DOCFIX-151's changelog) because the working tree currently carries OTHER in-flight, uncommitted changes from parallel agent sessions tonight (per the operator's own instruction that multiple agents are working concurrently) -- stashing would have touched their work, not just this delivery's. Instead, correctness was verified directly (the jq-independent invocation matrix above), and the only new gauntlet observation is the addition of the reenroll-hosts suite itself (previously absent, so it could not have been part of any prior baseline) failing for the same pre-existing, already-documented reason as its siblings -- not a regression this delivery introduced.
• Added $DC test cases to both existing harnesses (tests/carve-host-interfaces/run-tests.sh, tests/phase-00-maas-standup/run-tests.sh): a DC=dc0 explicit no-op case (must match the existing default-case assertions), and fail-loud cases for the blocked DC values, using a new run_dc() helper that skips fixture setup entirely (these calls exit at the selector, before the script ever reaches need_jq/a MAAS call, so they do not depend on the fixtures OR on jq being installed -- confirmed by invoking them directly, bypassing the harness's own jq gate, per the VERIFIED bullet above).
• Created tests/reenroll-hosts/run-tests.sh (no harness existed for this script before). Scoped narrowly to what this delivery actually changed: the $DC fail-loud/no-op matrix, plus a smoke test that --check's read-only reporting is unaffected when $DC is unset. Does not attempt to cover the create/poll/tag mutation paths (those need an interactive password prompt and a much heavier MAAS fixture set -- out of scope for a targeted parameterization change). Uses a minimal fake maas returning an empty machines list plus < /dev/null on stdin so a bug that ever reached the real interactive password prompt would fail loudly (EOF) instead of hanging the harness.

REVERT: git checkout HEAD~ -- scripts/reenroll-hosts.sh scripts/carve- host-interfaces.sh scripts/phase-00-maas-standup.sh tests/carve-host-interfaces/run-tests.sh tests/phase-00-maas-standup/run-tests.sh && rm -rf tests/reenroll-hosts (safe -- purely additive/opt-in; unset $DC behavior is provably unchanged, so no other script or runbook step that does not set $DC depends on any of this).

What this delivery does NOT close (be precise)

Tooling gap register item #15 has SEVEN sub-findings (enumerated in runbooks/dc-dc-phase3-maas-enlist-deploy.md's "Known gaps" section). This delivery closes ONLY the CLI-invocation half of sub-item 2 (the three scripts not accepting $DC at all). It does NOT:

• Invent any per-DC literal. No dc1/dc2 hostname, octet, boot MAC, or VIRSH_POWER_ADDRESS was added to lib-hosts.sh. lib_hosts_select_dc still fails loud for both dc1 and dc2, exactly as DOCFIX-151 left it -- that data gap is a separate, later delivery item (the Stage 4 runbook's own delivery checklist), not something this change works around.
• Make phase-00-maas-standup.sh's PLANES table dc2-aware. That table is a hardcoded D-052/D-053 literal, not derived from lib-net.sh's flat vars -- selecting dc1 happens to be correct today only because D-101 makes dc1's real target identical to dc0's, not because the script reads dc1-specific data. Once dc2 gets real NetBox CIDRs (gap #3), this table will need its own parameterization pass.
• Close sub-items 1 (no OpenTofu rack-controller module), 3 (node count/sizing undecided), 4 (dc2 blocked at the network-selector layer -- unrelated to this delivery, pre-existing), 5 (per-DC mirror ownership unconfirmed), 6 (VM-host-discovered MAAS status unconfirmed), or 7 (HOST_TAG/boot-fabric-name literals are DC0-specific). All six remain OPEN, unchanged by this delivery.

Next actionable step

docs/dc-dc-deployment-workflow.md item #15 and runbooks/dc-dc-phase3- maas-enlist-deploy.md's gap #2 / Steps 5 and 8 updated to reflect the partial closure (see those files' diffs). The next real dependency for sub-item 2's FULL closure is Stage 4's own execution: once it measures real per-DC hostnames/octets/boot MACs and a real per-DC PLANES table update gets authored, lib-hosts.sh and phase-00-maas-standup.sh's literal table go from "selector wired but fails loud" to "selector wired and populated" -- no further change to the three scripts themselves should be required for that.