Proxmox IaC Starter Kit

Proxmox IaC Starter Kit

The Proxmox Terraform provider is powerful but getting a real working setup — with cloud-init, SSH key injection, template cloning, and sensible variable structure — takes hours of trial and error. This kit is a tested, opinionated starting point that gets you provisioning VMs and LXCs from the command line on day one.

What's Included

• Terraform configs — main.tf, variables.tf, outputs.tf using the bpg/proxmox provider
• VM module — Clone from a template with CPU, RAM, disk, and network all parameterized
• LXC module — Provision containers with rootfs size, privileged/unprivileged toggle, and bind mounts
• cloud-init templates — User data snippets for SSH key injection, hostname, packages, and first-boot scripts
• Proxmox API token setup script — Creates the right role and token on your Proxmox host in one run
• Example: 3-VM homelab cluster — A working example provisioning a controller + 2 workers

Developer Experience

• API token auth — no root password in your state file
• Variables file lets you switch between nodes and storage pools without touching main.tf
• Outputs print the IP addresses of all provisioned resources
• Works with Proxmox VE 7.x and 8.x
• Fully compatible with OpenTofu if you prefer the open-source fork

What You Get

• main.tf, variables.tf, outputs.tf — core Terraform configuration
• modules/vm/ and modules/lxc/ — reusable resource modules
• cloud-init/ — user-data templates for common base images (Ubuntu, Debian, Alpine)
• scripts/setup-api-token.sh — run on your Proxmox host to create the Terraform service account
• examples/homelab-cluster/ — a complete working example you can adapt
• .env.example and terraform.tfvars.example — credential templates
• README.md — step-by-step setup, cloud-init tips, and common patterns

Requirements

Terraform 1.5+ (or OpenTofu). Proxmox VE 7.4+ with API access enabled. A VM template already uploaded to Proxmox (Ubuntu 24.04 cloud image recommended — setup instructions in README).