basha_infra

Hypervisor + VM layer for the home cluster. Owns machines; service repos own workloads. See ~/src/CLAUDE.md for the broader picture.

Layout

basha_infra/
├── inventory.yaml          # source of truth: Proxmox hosts, VMs, roles, host_volumes
├── template/               # NixOS Proxmox template builder
│   ├── flake.nix
│   ├── modules/
│   │   ├── proxmox-base.nix     # bootloader, networking, ssh — used by every VM
│   │   └── cluster-client.nix   # consul + nomad + docker + tailscale (client mode)
│   ├── hosts/
│   │   └── apps.nix             # per-VM nix config (hostname, meta.role)
│   └── Makefile                 # `make template` builds + uploads + registers
└── terraform/              # VM lifecycle
    ├── main.tf                  # bpg/proxmox: clones template per inventory.yaml
    ├── variables.tf
    └── outputs.tf

The control plane (Consul server, Nomad server, Vault) lives on the home NixOS box (~/src/nixos/), not here. VMs only run the client halves.

How it fits together

   template/             →  qmrestore → Proxmox template VMID 9001
                                              │
                                              │ qm clone
                                              ▼
   terraform/            →  cloned VMs (apps, postgres, …) per inventory.yaml
                                              │
                                              │ nixos-rebuild --target-host
                                              ▼
   template/hosts/<name>.nix lays the per-host config on top of the template

The template carries the cluster-client modules baked in, so a freshly cloned VM joins Consul + Nomad on first boot. Per-host overrides (hostname, meta.role, future host_volume mounts) are applied later via nixos-rebuild --target-host.

Bootstrap (first-time on a fresh Proxmox)

Prerequisites (one-off on Proxmox, see pveum/pvesm):

• terraform@pve user with an API token + Administrator on /
• local datastore has import and snippets content types enabled
• Your laptop's SSH key in root@<proxmox>:~/.ssh/authorized_keys

# 1. Build + register the template (VMID 9001)
cd template && make template

# 2. Fill in terraform.tfvars
cd ../terraform
cp terraform.tfvars.example terraform.tfvars
$EDITOR terraform.tfvars

# 3. Apply — clones a VM per inventory.yaml entry
terraform init
terraform apply

# 4. After first boot, SSH in via LAN IP (guest agent reports it),
#    run `tailscale up --authkey=...` once. Then from the laptop:
nixos-rebuild switch --flake ../template#apps --target-host root@apps

Add a new VM

1. Add an entry under vms: in inventory.yaml.
2. Add template/hosts/<name>.nix and a nixosConfigurations.<name> entry in template/flake.nix.
3. cd terraform && terraform apply clones the VM.
4. nixos-rebuild switch --flake template#<name> --target-host root@<lan-ip>.

Update an existing VM

Edit template/modules/cluster-client.nix or template/hosts/<name>.nix, then redeploy without recreating the VM:

nixos-rebuild switch --flake ./template#<name> --target-host root@<name>

If the change should also affect future clones, rebuild the template too: cd template && make template. (Existing VMs are not auto-recreated.)

Remove a VM

1. nomad node drain -enable -force <node-id> — evacuate jobs.
2. Delete the entry from inventory.yaml.
3. cd terraform && terraform apply — destroys the VM.

TODOs

• Move terraform state to Garage S3 backend (see ~/src/CLAUDE.md).
• Add postgres / garage / vault / forgejo hosts as stateful services migrate off the home box.
• Thread tailscale auth via nixos-rebuild so the one-time manual tailscale up after clone isn't needed.