Skip to main content
Provision VMs and LXCs from a single terragrunt apply. The first thing that runs.
tofu-proxmox defines every VM and LXC in the homelab as OpenTofu resources. Terragrunt provides DRY config across environments. The Proxmox provider talks to the cluster API; nothing here touches a host directly.

​
What it does

  • Reads its desired-state from the deployment.json contract — one versioned S3 object, fetched fail-loud, single-writer via the state lock
  • Defines compute, network, and storage for every homelab guest
  • Wraps the bpg/proxmox provider
  • Places guests across cluster nodes via a per-resource node_name (defaults to the primary node)
  • Declares per-node ZFS storage (node_storage) that Ansible provisions — OpenTofu references the datastore by id and never creates the pool itself (zpool create is an OS-level operation)
  • Uses Terragrunt to share variables across prod, staging, and one-off environments
  • Outputs a list of provisioned hosts that Ansible inventories consume directly

​
How it fits

UpstreamDownstream
Triggerterragrunt apply from the operatorOutputs an Ansible-ready inventory
Talks toProxmox cluster API (read/write)ansible-proxmox, ansible-proxmox-apps

​
Getting started

1

Clone and enter the dev shell

git clone https://github.com/JacobPEvans/terraform-proxmox && cd terraform-proxmox && nix develop
2

Provide Proxmox API credentials

Doppler resolves PROXMOX_VE_USERNAME, PROXMOX_VE_PASSWORD, and PROXMOX_VE_ENDPOINT at run time. The README.md covers the exact var names.
3

Apply

terragrunt run-all apply from the env folder. Review the plan; nothing destructive runs without confirmation.
4

Hand off to Ansible

Outputs are written to the file Ansible reads as its inventory. Run ansible-proxmox next.

ansible-proxmox

Configures the host once OpenTofu has provisioned it.

ansible-proxmox-apps

Deploys HAProxy, Cribl Edge, Cribl Stream on top.

tf-splunk-aws

The AWS-side equivalent for Splunk’s DR footprint.

Source on GitHub

Modules, examples, full README.