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

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

@ -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 <VMID> --name <hostname> --full
qm set <VMID> --memory 2048 --cores 2 \
--ciuser ansible \
--sshkeys /path/to/ansible_ed25519.pub \
--ipconfig0 ip=<IP>/24,gw=<GATEWAY>
qm start <VMID>
```
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 <repo> ~/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/<env>/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/<env>/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).
---