# v1 Deploy Runbook -- VR0 DC0 Omega Cloud (Caracal 2024.1, IPv4)

## Command-label convention
Every command block below is bracketed by bold labels, so a command line is never mistaken
for surrounding prose (these render in GitBucket and read clearly in a raw editor):
- **RUN -- LOC** -- the block CHANGES state; run it at LOC (e.g. `jumphost`, `vault/0`, `jumphost -> magnum/0`).
- **CHECK (read-only) -- LOC** -- a read-only verification; safe to re-run.
- **GATE:** -- a hard stop; do NOT proceed past the block unless the stated condition holds.
- **Expect:** -- what a passing result looks like.
- `> CAUTION:` -- marks a destructive, secret-handling, or irreversible step.

The deploy is a gated sequence: run `phase-00` through `phase-08` in order. Each phase
ends in a hard gate (an explicit pass/fail check); do not start the next phase until the
current gate passes. The two appendices are reference, not steps.

## Conventions

- **RUN location.** Every command block is tagged with where it runs: `# RUN: jumphost`
  (the `vopenstack-jesse` jumphost, with `juju` + the openstack CLI), `# RUN: mgmt VM`
  (the in-cloud CAPI management VM, reached over SSH), or a charm unit via
  `juju ssh <unit> -- '...' </dev/null`.
- **Gates.** A line beginning `GATE:` or `EXIT GATE` is a stop-and-verify. Read-only
  verification precedes every mutation; destructive and secret-handling steps are
  individually gated, never batched.
- **Dynamic lookups.** VIPs, project names, IDs, and version constellations are
  discovered at run time, not hardcoded. Site-specific literals are tagged `ENV(...)`
  for the eventual generalization pass toward Roosevelt.
- **ASCII only.** All runbook content is ASCII (a mod_wsgi UnicodeDecodeError lesson);
  keep it that way on edit.

## Phases

| #  | File                                    | Purpose                                              | Decisions             |
| -- | --------------------------------------- | ---------------------------------------------------- | --------------------- |
| 00 | phase-00-teardown-maas-reset.md         | Destroy the model + reset MAAS to a clean rebuild    | KI-P3-001             |
| 01 | phase-01-bundle-deploy.md               | Octavia PKI overlay + `juju deploy` + settle wait    |                       |
| 02 | phase-02-vault-bringup.md               | Vault init/unseal + cert cascade (PKI root)          | manual unseal = v1 std |
| 03 | phase-03-core-verify.md                 | Settle, regenerate admin-openrc, verify Horizon      |                       |
| 04 | phase-04-network-carve.md               | Provider external network + IPAM reference           |                       |
| 05 | phase-05-octavia-enablement.md          | Enable Octavia (amphora)                             | D-021                 |
| 06 | phase-06-incloud-mgmt-cluster.md        | In-cloud single-homed CAPI management cluster        | D-035                 |
| 07 | phase-07-conductor-graft.md             | Trustee domain-setup + graft the magnum-capi-helm driver | D-031 / D-037 / D-042 / D-046 / D-047 |
| 08 | phase-08-workload-cluster-acceptance.md | End-to-end tenant cluster + acceptance bar           | D-011 (amended D-019) |

## Appendices

- **appendix-A-troubleshooting.md** -- symptom -> cause -> fix index, keyed by
  D-NNN / DOCFIX-NNN / lesson.
- **appendix-B-asbuilt-version-lock.md** -- charm channels, the CAPI version
  constellation, and the magnum-capi-helm driver pin.

## History

This `phase-NN` set supersedes the earlier `v1-do-doc-NN-*` execution documents (and the
older `NN-*.md` set and the `deprecated/` folder), which were removed in the repo
sanitation sweep. Git history preserves them.

- ops-capi-recovery.md -- parking, restart, and LB repair for the CAPI/Magnum stack (post-deploy operations companion; not a deploy phase). Added 2026-06-10.