From b89ca8835a2921a3196573ab0a4746c1dc3f8e04 Mon Sep 17 00:00:00 2001 From: sjat Date: Fri, 5 Jun 2026 09:44:31 +0200 Subject: [PATCH] new-host runbook: control node ubongo is bare-metal Co-Authored-By: Claude Sonnet 4.6 --- docs/runbooks/new-host.md | 42 ++++++++++++++++++++++----------------- 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/docs/runbooks/new-host.md b/docs/runbooks/new-host.md index 1e23c33..1e26905 100644 --- a/docs/runbooks/new-host.md +++ b/docs/runbooks/new-host.md @@ -2,7 +2,8 @@ ## Prerequisites -- Proxmox VM template exists (Debian 13 cloud-init image — see below if not) +- Proxmox VM template exists (Debian 13 cloud-init image — see below if not). + Not needed for the control node `ubongo`, which is bare-metal (Part E). - `rbw` is installed and unlocked (`rbw unlock`) so the vault password resolves from Vaultwarden - The host's intended hostname and IP are decided @@ -110,27 +111,32 @@ make check PLAYBOOK=site --- -## Part E — Control node (manual exception) +## Part E — Control node (`ubongo`, manual exception) The control node runs Terraform and Ansible, so it cannot be created by the -Terraform it hosts (chicken-and-egg). It is the **one** host provisioned manually — -see ADR-009 and the control-node section of ADR-005. Use the template from Part A: +Terraform it hosts (chicken-and-egg). It is `ubongo`, a dedicated **physical** +machine outside the cluster — not a Proxmox guest. It is the **one** host +provisioned manually. Rationale, hardware target, and recovery model: ADR-015. -```bash -# Clone the template by hand (Proxmox UI or qm clone) -qm clone 9000 --name --full -qm set --memory 2048 --cores 2 \ - --ciuser ansible \ - --sshkeys /path/to/ansible_ed25519.pub \ - --ipconfig0 ip=/24,gw= -qm start -``` +1. Install Debian 13 on the physical box by hand (no template to clone). +2. Create the `ansible` user and install its SSH public key. +3. Set up the Ansible environment on it: + ```bash + git clone ~/ansible + cd ~/ansible + make setup # venv + Python deps + make collections # Ansible collections + rbw login && rbw unlock # vault password from Vaultwarden (see rotate-secrets.md) + ``` +4. Join the mesh VPN (choice deferred — see ADR-015) so it is reachable over SSH + from elsewhere. +5. Add `ubongo` to `inventories//hosts.yml` under the `control` group. -Then set up the Ansible environment on it (`make setup`, `make collections`, set up -`rbw` and `rbw unlock`) per ADR-005, and add it to `inventories//hosts.yml` under the -`control` group. Because the control node is not in `local.vms`, this is the only -case where editing `hosts.yml` by hand is expected — every other host comes from -`make tf-inventory`. +Because `ubongo` is not in `local.vms`, this is the only case where editing +`hosts.yml` by hand is expected. **Known limitation:** `make tf-inventory` +regenerates `hosts.yml` from Terraform outputs and will overwrite a hand-added +`control` entry — re-add `ubongo` after running it (preserving the control entry in +the generator is tracked separately, not yet built). ---