Changelog 2026-07-09 -- Stage 1 runbook: Phase 0 vcloud host prep (DOCFIX-153)

No live infrastructure touched -- new runbook document only. Operator clarified this session runs from the workstation (not the vopenstack-jesse jumphost or the vcloud host); tonight's scope is prep so tomorrow morning's switch to the vcloud host can execute against real infrastructure immediately. This is the FIRST runbook that will be, since Stage 0 (ratification) is a decision-record exercise, not an infrastructure step.

Item

1. DOCFIX-153 -- runbooks/dc-dc-phase0-vcloud-prep.md

FILES: runbooks/dc-dc-phase0-vcloud-prep.md (new), docs/dc-dc-deployment- workflow.md (Stage 1 row + tracker table updated).

WHAT: command-level runbook for buildout-design Section 4's Phase 0 (turn the bare vcloud host into a substrate Office1 can deploy from), matching this repo's established runbook conventions (see runbooks/phase-00- teardown-maas-reset.md as the style template): a sequence table, read-only CHECK blocks before every mutation, each MUTATION individually gated, an explicit gate section at the end, and a delivery checklist.

Eleven steps: identify the target host + confirm libvirt reach; measure CPU/RAM/disk and CPU virtualization-extension support; measure host L2 MTU and record the D-101 MTU decision (jumbo vs. 1500-with-reduced-tenant-MTU) plus the Ceph size=3-vs-size=2 disk-budget plausibility check (Section 3's three Phase-0 gates); enable nested KVM if not already on; prepare libvirt storage pool paths for DC1 and Office1 (explicitly NOT DC2 -- no CIDRs assigned yet, gap #3's data half); install/confirm OpenTofu and registry reach; write a dc-dc-phase0.auto.tfvars file from the session's measured values (with maas_api_key explicitly kept OUT of any committed file, via TF_VAR_maas_api_key instead); tofu init/validate/fmt; tofu plan reviewed line-by-line against an explicit expected-resource list before tofu apply; post-apply verification against the Phase-0 gate criteria.

Genuine open question surfaced and flagged, not silently resolved: opentofu/main.tf declares the MAAS provider block unconditionally, even though this Phase-0 stage's plan only touches libvirt resources (planes, pools, mesh links) -- no MAAS resource is instantiated until Stage 3. It is not yet known whether tofu init/plan will demand real maas_api_url/maas_api_key values before Stage 2 has even stood up MAAS. The runbook documents both possible outcomes and what to do for each (placeholder values IF plan-time validation only checks non-null, vs. a logged structural finding -- splitting the MAAS provider into a Stage-3-only root module -- if OpenTofu actually attempts real connectivity at plan time with zero MAAS resources). This is exactly the kind of thing this runbook is supposed to catch by being read carefully before tomorrow's execution, rather than being discovered live.

Also flagged, not silently assumed: if the vcloud host tomorrow is the SAME physical host that ran the VR0/DC0 single-DC testcloud (buildout-design's own Ground Truth section implies this -- the "~256 vCPU/1 TiB/1 TiB disk dedicated to VR1" host is a repurposing, not a new machine), Step 5 tells the operator to check for an existing libvirt storage pool at any candidate path before creating DC1's pool there, to avoid a silent path collision with VR0's own pool.

VERIFIED: bash scripts/repo-lint.sh 0 fail, 1 documented legacy warn (unchanged -- prose-only addition, no script logic touched). This runbook itself is NOT YET EXECUTED -- that is tomorrow morning's work, per the operator's own plan; nothing in this delivery claims otherwise.

REVERT: rm runbooks/dc-dc-phase0-vcloud-prep.md && git checkout HEAD~ -- docs/dc-dc-deployment-workflow.md (safe -- no infrastructure has been touched by this delivery, purely a document).

Next actionable step

This runbook is the hand-off artifact for tomorrow morning's switch to the vcloud host. Stage 2 (Office1 headend standup) is the next runbook to draft tonight, continuing while the operator is away -- its content depends on Stage 1 actually having run (real libvirt reach, pool paths, MTU decision) only loosely; it can be drafted in parallel since MAAS-region/NetBox/ GitBucket/Tailscale standup on Office1 is a mostly independent set of steps once OpenTofu itself is confirmed working.