While Proxmox has a great web UI, infrastructure-as-code lets you:
Automate repeatable VM deployments
Keep configurations under version control
Easily spin up multi-VM Setups
Reduce human error
👋 Quick heads-up!
This guide is Part 2 of a multi-part series.
In this article, we’ll walk through How to Deploy a Virtual Machine in proxmox Using Terraform
👉 Jump to Part 1: How to Set Up Proxmox with Terraform →
📦 Prerequisites
Before you begin, make sure you have:
✅ A running Proxmox VE host or cluster
✅ A user with API access (e.g., terraform-user@pve)
✅ A cloud-init template VM ready to be cloned
✅ Terraform installed on your machine
✅ Installed the Telmate Proxmox Terraform provider
🗂 Project Directory Structure
Here’s the structure of the deployment repo we’ll use:
proxmox-vm-deploy/
├── main.tf
├── provider.tf
├── variables.tf
├── terraform.tfvars
Let’s go through each file.
terraform {
required_providers {
proxmox = {
source = "Telmate/proxmox"
version = "3.0.2-rc01"
}
}
}
provider "proxmox" {
pm_api_url = var.proxmox_api_url
pm_parallel = 1
pm_debug = false
pm_tls_insecure = true
}
This sets up the connection to your Proxmox host. Make sure:
The user exists in Proxmox (pveum user add terraform-user@pve)
A suitable role (e.g., Terraform_Provisioner) with VM permissions is assigned
load the API tokens for connecting to proxmox as environment variables
👉 Check out part-1 of the series for a step-by-step guide on creating the required users, roles and tokens to connect via terraform
variable "vm_name" {
type = string
}
variable "clone" {
type = string
}
variable "ipconfig0" {
type = string
}
variable "vmid" {
type = number
}
variable "memory" {
type = number
}
variable "cores" {
type = number
}
variable "disk_size" {
type = string
description = "The size of the disk, should be at least as big as the disk in the template"
default = "20G"
}
variable "storage" {
type = string
description = "the storage where the VM disk will be created"
}
variable "ssh-public-key" {
type = string
description = "SSH public key for the VMs"
sensitive = true
}
variable "proxmox_api_url" {
type = string
description = "Proxmox API URL"
}
variable "target_node" {
type = string
description = "The Proxmox node where the VM will be created"
}
variable "nameserver" {
type = string
description = "Nameserver for the VM"
default = "1.1.1.1 8.8.8.8"
}
variable "cicustom" {
type = string
description = "Cloud-Init custom configuration"
default = "vendor=local:snippets/qemu-guest-agent.yml"
}
variable "cipassword" {
type = string
description = "Cloud-Init password for the VM"
sensitive = true
}
These variables define how your VM will look—name, clone template, IP config, memory, CPU, etc.
ssh-public-key = "ssh-ed25519 AAAAC3NzaC1lZXXXXXXXXXXXXXXXXXXXXXXwSOCiZ/OkpPDR3bR2tK4STIm+gnJk"
target_node = "proxmox-server-IP"
cicustom = "value=local:snippets/install-packages.yml"
cipassword = "ubuntu"
ipconfig0 = "ip=dhcp"
vmid = 1000
vm_name = "ubuntu-vm"
clone = "ubuntu-24-04-cloudinit-copy"
cores = 4
memory = 4096
nameserver = "1.1.1.1 8.8.8.8"
disk_size = "20G"
storage = "hdd-vm-data"
This is your configuration layer—values you want to pass to variables. Keep this file out of version control (.gitignore) if it includes sensitive info.
🏗 main.tf – Create the Virtual Machine
resource "proxmox_vm_qemu" "ubuntu-vm" {
vmid = var.vmid
name = var.vm_name
target_node = var.target_node
agent = 1
cpu {
cores = var.cores
sockets = 1
numa = true
type = "x86-64-v2-AES"
}
memory = var.memory
bios = "ovmf"
boot = "order=scsi0"
clone = var.clone
scsihw = "virtio-scsi-single"
vm_state = "running"
automatic_reboot = true
cicustom = var.cicustom
ciupgrade = true
nameserver = var.nameserver
ipconfig0 = var.ipconfig0
skip_ipv6 = true
ciuser = "root"
cipassword = var.cipassword
sshkeys = var.ssh-public-key
serial {
id = 0
}
efidisk {
efitype = "4m"
storage = "hdd-vm-data"
}
disks {
scsi {
scsi0 {
disk {
storage = var.storage
size = var.disk_size
}
}
scsi1 {
cloudinit {
storage = "hdd-vm-data"
}
}
}
}
network {
id = 0
bridge = "vmbr0"
model = "virtio"
}
}
Here’s what it does:
Clones an existing cloud-init-enabled VM template
Assigns VM name, IP, memory, CPU, etc.
Injects cloud-init config, such as SSH key and default user
Enables QEMU guest agent to enhance functionality
▶️ How to Run It
Open a terminal inside the project directory and follow these steps:
export PM_API_TOKEN_ID='terraform-user@pve!tf_token'
export PM_API_TOKEN_SECRET="XXXXXX-XXXX-XXXXX-XXXX-XXXXXXXXXXX"
terraform init
terraform plan
terraform apply
✅ Verify in Proxmox
Go to your Proxmox Web UI
You’ll see a the VM
Confirm network and SSH access
Check if the VM booted from your template and has your custom config
🛠 Troubleshooting Tips
SSH not working? Ensure cloud-init was enabled in your template and your public SSH key is valid.
Error: Permission denied? Double-check the Proxmox user's role and permissions.
Wrong IP? Validate your ipconfig0 syntax (should follow ip=x.x.x.x/xx,gw=x.x.x.x).
🧪 What’s Next?
Once you get one VM working, you can:
Create multiple VMs using for_each
Automate post-deploy scripts via null_resource and remote-exec
Turn this into a Kubernetes cluster or homelab infra stack!
