🏡 Homelab VI: Terraforming Proxmox

5 minute read

In the previous part of this series, I configured a template VM with cloud-init configs for zero intervention VM automation after provision.

In this part, I’ll setup a basic HashiCorp Terraform project for infrastructure as code (IaC) to provision the guest VMs and containers from Proxmox. This will be a great foundation for the homelab, as Terraform can be expanded to cloud automation as well, such as managing Cloudflare DNS records.

What is Terraform?

Terraform is a powerful tool from HashiCorp, they explain it pretty well:

Terraform is an open-source infrastructure as code software tool that provides a consistent CLI workflow to manage hundreds of cloud services. Terraform codifies cloud APIs into declarative configuration files.

(When people mention IaC, 9 times out of 10 it’s referring to Terraform.)

It’s an extremely popular tool due to it’s easy to learn declarative language (HCL) and extensive cloud provider support. Plus, the entire deployment process is so simple, it’s just two commands: terraform plan and terraform apply.

Installing Terraform locally

Terraform can be found on most package managers, and they have binaries as well. I’ll be placing all of the configuration within a terraform directory on my homelab repository at robherley/homelab.

Creating an automation user

Similar to Ansible, an API user for Proxmox will need to be created for Terraform.

On one of the Proxmox nodes, make a terraform user, add it to the automation group, and set a password:

root@r720$ pveum user add terraform@pve --groups automation --password <some password>


There’s a Proxmox provider on the Terraform registry, this’ll be the coupling for Terraform to communicate to the Proxmox API and understand how to reconcile the defined Terraform state.

First, Terrafrom needs to know about the Proxmox provider.

In terrafrom/

terraform {
  required_providers {
    proxmox = {
      source  = "telmate/proxmox"
      version = "2.9.4"

Then, Terraform can be initialized and install the defined plugin:

rob@macbook$ terraform init

Initializing the backend...

Initializing provider plugins...
- Finding telmate/proxmox versions matching "2.9.4"...
- Installing telmate/proxmox v2.9.4...
- Installed telmate/proxmox v2.9.4 (self-signed, key ID A9EBBE091B35AFCE)


Terraform has been successfully initialized!

To actually connect Proxmox and Terraform, a provider needs be defined.

In terraform/

provider "proxmox" {
  pm_parallel     = 1
  pm_tls_insecure = true
  pm_debug        = true
  pm_api_url      = var.pm_api_url
  pm_password     = var.pm_password
  pm_user         = var.pm_user

This is the basic configuration for the provider, most is self explanatory. The pm_parallel command is set to only allow one Proxmox operation at a time.

The var.* parameters are special, those’ll be defined in a variables file.


Terraform has input variables, which let you customize aspects of Terraform modules without altering the module’s own source code. Input variables are declared in blocks within .tf files, and their actual values are in a .tfvars file.

In terraform/

variable "pm_api_url" {
  default = ""

variable "pm_user" {
  default = "terraform@pve"

variable "pm_password" {
  sensitive = true

variable "vm_template_name" {
  default = "ubuntu-cloudinit-template"

variable "lxc_template_name" {
  default = "ubuntu-ct-template"

Most of these variable blocks are using default, which makes the variable optional. This is just because I’m lazy and I’m just defining any public variables here. The pm_password var is sensitive (not shown in Terraform output) with no default, and it will be defined in a .tfvars file that won’t be checked into git. As for the *_template_name variables, those’ll be used in a bit.

In terraform/terraform.tfvars, add the terraform Proxmox user password:

pm_password = "correct-horse-battery-staple"

Now, the actual resources can be defined. And like anything else in HCL, it’s denoted in a block syntax.

In terraform/

resource "proxmox_vm_qemu" "tf-test" {
  name        = "tf-test"
  target_node = "r720"
  clone       = var.vm_template_name

  cores       = 4
  memory      = 8192
  agent       = 1

This will create a VM with the name tf-test, which will be a full clone of var.vm_template_name that was defined in Unfortunately unlike the qm clone command, the attributes of the VM are not carried over in this provider’s Terraform clone (it’s programmed to use defaults instead) so the bare minimal parameters are specified.

💡 For explanations of all the parameters, see the provider’s argument reference.

To plan the change, run terraform plan:

rob@macbook$ $ terraform plan

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following
  + create

Terraform will perform the following actions:

  # will be created
  + resource "proxmox_vm_qemu" "tf-test" {
      + additional_wait           = 0
      + agent                     = 1
      + automatic_reboot          = true
      + balloon                   = 0
      + bios                      = "seabios"
      + boot                      = "c"
      + bootdisk                  = (known after apply)
      + clone                     = "ubuntu-cloudinit-template"
      + clone_wait                = 0
      + cores                     = 4
      + cpu                       = "host"
      + default_ipv4_address      = (known after apply)
      + define_connection_info    = true
      + force_create              = false
      + full_clone                = true
      + guest_agent_ready_timeout = 100
      + hotplug                   = "network,disk,usb"
      + id                        = (known after apply)
      + kvm                       = true
      + memory                    = 8192
      + name                      = "tf-test"
      + nameserver                = (known after apply)
      + numa                      = false
      + onboot                    = false
      + oncreate                  = true
      + preprovision              = true
      + reboot_required           = (known after apply)
      + scsihw                    = (known after apply)
      + searchdomain              = (known after apply)
      + sockets                   = 1
      + ssh_host                  = (known after apply)
      + ssh_port                  = (known after apply)
      + tablet                    = true
      + target_node               = "r720"
      + unused_disk               = (known after apply)
      + vcpus                     = 0
      + vlan                      = -1
      + vmid                      = (known after apply)


Once the plan is confirmed to be okay, it can be applied:

rob@macbook$ $ terraform apply
... Creating... Still creating... [10s elapsed] Still creating... [20s elapsed] Still creating... [30s elapsed] Still creating... [40s elapsed] Still creating... [50s elapsed] Still creating... [1m0s elapsed] Creation complete after 1m3s [id=r720/qemu/101]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Now to double check with Ansible:

rob@macbook$ ansible proxmox_all_running -m ping
tf-test | SUCCESS => {
    "ansible_facts": {
        "discovered_interpreter_python": "/usr/bin/python3"
    "changed": false,
    "ping": "pong"

Perfect! The homelab infrastructure is now fully declarative and automated.

Note: during testing, I have found the provider to be flaky at points when determining if the VM or LXC is created or not. Apparently this is a known issue with the provider, due to a bug when interacting with Proxmox conf locks. Either the provider can be downgraded to version 2.8.0 or existing resources can be imported into Terraform’s state like so:

# terraform import <resource type>.<resource name> <node>/<type>/<vmid>
rob@macbook$ terraform import r720/qemu/101


Well, that’s it for the homelab series! I think six parts is enough to conclude. The homelab is now a fully operational virtualization cluster with redundant ZFS (and NFS) storage, VM/LXC templates, automated with Ansible and provisioned via IaC with Terraform. There may be separate one-offs for TrueNAS, Kubernetes or OpenShift clusters, but no promises. Thanks for tagging along!

Prev Next