# 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.