sjat/boma
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

new-host runbook: control node ubongo is bare-metal

Browse source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
sjat 2026-06-05 09:44:31 +02:00
parent 3fb780c286
commit b89ca8835a
1 changed files with 24 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
docs/runbooks/new-host.md
View file

@ -2,7 +2,8 @@
## Prerequisites ## 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 - `rbw` is installed and unlocked (`rbw unlock`) so the vault password resolves from Vaultwarden
- The host's intended hostname and IP are decided - 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 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 — Terraform it hosts (chicken-and-egg). It is `ubongo`, a dedicated **physical**
see ADR-009 and the control-node section of ADR-005. Use the template from Part A: machine outside the cluster — not a Proxmox guest. It is the **one** host
provisioned manually. Rationale, hardware target, and recovery model: ADR-015.
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 ```bash
# Clone the template by hand (Proxmox UI or qm clone) git clone <repo> ~/ansible
qm clone 9000 <VMID> --name <hostname> --full cd ~/ansible
qm set <VMID> --memory 2048 --cores 2 \ make setup # venv + Python deps
--ciuser ansible \ make collections # Ansible collections
--sshkeys /path/to/ansible_ed25519.pub \ rbw login && rbw unlock # vault password from Vaultwarden (see rotate-secrets.md)
--ipconfig0 ip=<IP>/24,gw=<GATEWAY>
qm start <VMID>
``` ```
4. Join the mesh VPN (choice deferred — see ADR-015) so it is reachable over SSH
from elsewhere.
5. Add `ubongo` to `inventories/<env>/hosts.yml` under the `control` group.
Then set up the Ansible environment on it (`make setup`, `make collections`, set up Because `ubongo` is not in `local.vms`, this is the only case where editing
`rbw` and `rbw unlock`) per ADR-005, and add it to `inventories/<env>/hosts.yml` under the `hosts.yml` by hand is expected. **Known limitation:** `make tf-inventory`
`control` group. Because the control node is not in `local.vms`, this is the only regenerates `hosts.yml` from Terraform outputs and will overwrite a hand-added
case where editing `hosts.yml` by hand is expected — every other host comes from `control` entry — re-add `ubongo` after running it (preserving the control entry in
`make tf-inventory`. the generator is tracked separately, not yet built).
--- ---