boma/docs/decisions/006-terraform.md

ADR-006 — Terraform for infrastructure provisioning

Context

Ansible manages host configuration well but has no state model for infrastructure existence. Adding Terraform handles the "what exists" layer — creating and destroying VMs on Proxmox — while Ansible continues to own everything that runs inside them, including all internal DNS records.

This complements rather than replaces Ansible. The two tools do not overlap. The exact boundary, handoff pipeline, and data contract between them live in ADR-009 (provisioning handoff) — this ADR covers Terraform's own internals only.

---

Responsibility split

The canonical responsibility-split table lives in ADR-009. In short: Terraform owns VM existence only; Ansible owns everything inside a VM, including all internal DNS records.

OPNsense is entirely Ansible. The available Terraform providers for OPNsense are community-maintained with real risk of provider rot across OPNsense releases. OPNsense firewall rules also change on a service cadence, not an infrastructure cadence, making them a poor fit for Terraform state.

---

Providers

bpg/proxmox (~> 0.70): Chosen over telmate/proxmox for active maintenance, full Proxmox 8 API support, and better cloud-init integration. This is the only provider.

Terraform does not manage DNS. An earlier design used hashicorp/dns (RFC 2136) to write A records, but that created a bootstrap cycle — the first DNS server cannot register itself — and split DNS ownership across two tools. Ansible's dns role now owns the entire internal zone, rendered from inventory. See ADR-009.

Terraform manages its own provider dependencies via required_providers and .terraform.lock.hcl (tracked in git once terraform init has been run).

---

State backend

Choice: Local state on the control node.

Forgejo (Gitea-based) has no usable Terraform HTTP state backend — its API /raw/ endpoint is read-only, so state cannot be written there. State therefore lives locally as terraform.tfstate (gitignored) on the control node, which is persistent and backed up with the rest of the node.

At this scale (solo operator, a handful of VMs) local state is sufficient: no concurrent applies, so no remote locking is needed. If a remote backend with locking becomes worthwhile later, add a backend block to backend.tf pointing at a real backend such as MinIO/S3 — Forgejo is not an option. See ADR-010 for the Forgejo integration boundary.

---

Structure

terraform/
  modules/
    proxmox_vm/          # reusable VM module — Proxmox only, no DNS
  environments/
    staging/             # staging VMs, separate state file
    production/          # production VMs, separate state file

Separate environment directories (not Terraform workspaces) for the clearest isolation — no risk of accidentally applying the wrong state.

Each environment directory contains:

• providers.tf — provider version pins and configuration
• backend.tf — Forgejo state backend (environment-specific path)
• variables.tf — input declarations
• terraform.tfvars.example — tracked template; copy to terraform.tfvars for actual values
• main.tf — local.vms map and module calls (no DNS resources)
• outputs.tf — VM map consumed by make tf-inventory

---

Secrets handling

The only secret input (the Proxmox API token) is passed via a TF_VAR_* environment variable and declared sensitive = true in variables.tf. It never appears in .tfvars files. Non-secret configuration lives in tracked terraform.tfvars.example; the real terraform.tfvars is gitignored.

---

Ansible integration

After terraform apply, run make tf-inventory TF_ENV=<env> to regenerate inventories/<env>/hosts.yml from the vms output. The full handoff pipeline, the vms output → inventory data contract, and the generator script (scripts/tf_to_inventory.py) are documented in ADR-009 (provisioning handoff).

---

What was ruled out

Option	Reason
telmate/proxmox provider	Less actively maintained; weaker cloud-init and Proxmox 8 support
OPNsense Terraform provider	Community-maintained; provider rot risk across OPNsense releases
Terraform workspaces	Single state file with workspace prefix; accidental cross-env apply possible
Separate Terraform repo	Cross-referencing between infra and config adds friction; monorepo keeps the full picture together