personal_infra/tofu/nodito/README.md

## Nodito VMs with OpenTofu (Proxmox)

This directory lets you declare VMs on the `nodito` Proxmox node and apply with OpenTofu. It clones the Ansible-built template `debian-13-cloud-init` and places disks on the ZFS pool `proxmox-tank-1`.

### Prereqs
- Proxmox API token with VM privileges. Example: user `root@pam`, token name `tofu`.
- OpenTofu installed.
    ```
    sudo apt-get update
    sudo apt-get install -y apt-transport-https ca-certificates curl gnupg

    sudo install -m 0755 -d /etc/apt/keyrings
    curl -fsSL https://get.opentofu.org/opentofu.gpg | sudo tee /etc/apt/keyrings/opentofu.gpg >/dev/null
    curl -fsSL https://packages.opentofu.org/opentofu/tofu/gpgkey | sudo gpg --no-tty --batch --dearmor -o /etc/apt/keyrings/opentofu-repo.gpg >/dev/null
    sudo chmod a+r /etc/apt/keyrings/opentofu.gpg /etc/apt/keyrings/opentofu-repo.gpg

    echo \
      "deb [signed-by=/etc/apt/keyrings/opentofu.gpg,/etc/apt/keyrings/opentofu-repo.gpg] https://packages.opentofu.org/opentofu/tofu/any/ any main
    deb-src [signed-by=/etc/apt/keyrings/opentofu.gpg,/etc/apt/keyrings/opentofu-repo.gpg] https://packages.opentofu.org/opentofu/tofu/any/ any main" | \
      sudo tee /etc/apt/sources.list.d/opentofu.list > /dev/null
    sudo chmod a+r /etc/apt/sources.list.d/opentofu.list

    sudo apt-get update
    sudo apt-get install -y tofu
    tofu version
    ```
- The Ansible template exists: `debian-13-cloud-init` (VMID 9001 by default).

### Provider Auth
Credentials are the only thing not in git. Copy `terraform.tfvars.example` to
`terraform.tfvars` (gitignored) and set:
- `proxmox_api_url` (e.g. `https://nodito:8006/api2/json`)
- `proxmox_api_token_id` (e.g. `root@pam!tofu`)
- `proxmox_api_token_secret`

Alternatively, export them as `TF_VAR_proxmox_api_token_secret` etc.

### Declare VMs
VMs are declared in `vms.auto.tfvars`, which is committed. `*.auto.tfvars` is
loaded automatically, so it needs no `-var-file`. Example entry:
```
vms = {
  web1 = {
    name         = "web1"
    cores        = 2
    memory_mb    = 2048
    disk_size_gb = 20
    ipconfig0    = "ip=dhcp" # or "ip=192.168.1.50/24,gw=192.168.1.1"
  }
}
```

All VM disks are created on `zfs_storage_name` (defaults to `proxmox-tank-1`). Network attaches to `vmbr0`. VLAN can be set per-VM with `vlan_tag`.

### Usage
```
tofu init
tofu plan
tofu apply
```
`terraform.tfvars` and `vms.auto.tfvars` are both auto-loaded.

> VMs are created once and then protected: the module sets `lifecycle.prevent_destroy = true` and ignores subsequent config changes. After the initial apply, manage day‑2 changes directly in Proxmox (or remove the lifecycle block if you need OpenTofu to own ongoing updates).

### Notes
- Clones are full clones by default (`full_clone = true`).
- Cloud-init injects `cloud_init_user` and `ssh_authorized_keys`.
- `.terraform.lock.hcl` is committed: it pins the provider hashes, which matters
  because `versions.tf` tracks a release candidate (`3.0.2-rc05`).
- State is local (`terraform.tfstate`, gitignored) and has no remote backend, so
  it exists only on the machine that last ran `tofu apply`.
- The map is not a complete inventory of nodito: state also manages
  `bastion-box` (1100) and `nonkeiwaisi-box` (3300), which are not declared in
  `vms.auto.tfvars`. `tofu plan` is clean today, but relaxing the `lifecycle`
  block without first declaring them would put them up for destruction.
- Disks use `scsi0` on ZFS with `discard` enabled.