Proxmox VM Terraform Module

A Terraform module for creating and managing Proxmox VMs using the Telmate/proxmox provider.

Usage

Clone from template

module "vm" {
  source = "github.com/valueiron/pvevm"

  name        = "web-01"
  target_node = "pve-node-1"
  clone       = "ubuntu-24.04-template"
  storage     = "local-lvm"

  instance_size = "medium"

  ciuser    = "ubuntu"
  sshkeys   = file("~/.ssh/id_rsa.pub")
  ipconfig0 = "ip=192.168.10.10/24,gw=192.168.10.1"
}

Multiple VMs with for_each

locals {
  vms = {
    web1 = { name = "web-1", target_node = "pve-node-1", ipconfig0 = "ip=192.168.10.11/24,gw=192.168.10.1" }
    db1  = { name = "db-1",  target_node = "pve-node-2", ipconfig0 = "ip=192.168.10.21/24,gw=192.168.10.1" }
  }
}

module "vm" {
  source   = "github.com/valueiron/pvevm"
  for_each = local.vms

  name        = each.value.name
  target_node = each.value.target_node
  clone       = "ubuntu-24.04-template"
  storage     = "local-lvm"

  instance_size = "small"
  ipconfig0     = each.value.ipconfig0

  ciuser  = "ubuntu"
  sshkeys = file("~/.ssh/id_rsa.pub")
}

# Access outputs per VM key
output "vm_ids" {
  value = { for k, m in module.vm : k => m.vm_id }
}

Multiple NICs and additional disks

module "vm" {
  source = "github.com/valueiron/pvevm"

  name        = "storage-node"
  target_node = "pve-node-1"
  clone       = "ubuntu-24.04-template"
  storage     = "local-lvm"

  instance_size = "large"

  networks = [
    { model = "virtio", bridge = "vmbr0", tag = 100 },
    { model = "virtio", bridge = "vmbr0", tag = 200, rate = 1000 },
  ]

  additional_disks = [
    { type = "scsi", slot = 2, storage = "nvme2-ceph", size = "100G" },
    { type = "scsi", slot = 3, storage = "nvme2-ceph", size = "500G" },
  ]

  ciuser    = "ubuntu"
  sshkeys   = file("~/.ssh/id_rsa.pub")
  ipconfig0 = "ip=dhcp"
  ipconfig1 = "ip=dhcp"
}

Boot from ISO

module "vm" {
  source = "github.com/valueiron/pvevm"

  name        = "install-vm"
  target_node = "pve-node-1"
  storage     = "local-lvm"

  size   = "40G"
  iso    = "local:iso/ubuntu-24.04-server-amd64.iso"
  ostype = "l26"
}

PXE boot

module "vm" {
  source = "github.com/valueiron/pvevm"

  name        = "pxe-vm"
  target_node = "pve-node-1"
  storage     = "local-lvm"

  instance_size = "small"
  pxe           = true
  bridge        = "vmbr0"
  tag           = 100
}

Instance sizes

Size	Memory	Cores	Sockets	vCores	Disk
xsmall	2 GiB	1	1	1	10G
small	4 GiB	2	1	2	12G
medium	8 GiB	4	1	4	20G
large	16 GiB	8	1	8	40G
xlarge	32 GiB	10	1	10	60G

When instance_size is empty (the default), the small preset is used as the fallback. The memory, size, and cpu inputs always take precedence over the preset.

To add custom presets, pass a replacement map via instance_sizes.

Requirements

Name	Version
terraform	>= 1.3.0
proxmox	~> 3.0

Providers

Name	Version
proxmox	~> 3.0

Modules

No modules.

Resources

Name	Type
proxmox_vm_qemu.pvevm	resource

Inputs

Name	Description	Type	Default	Required
additional_disks	Additional disks to attach beyond the scsi0 boot disk and cloud-init disk. Only 'scsi' type is supported. Slots 0 and 1 are reserved; use slots 2–5.	list(object({ type = string storage = string size = string slot = number }))	[]	no
agent	Enable QEMU Guest Agent (1 enabled, 0 disabled)	number	1	no
boot	Boot order specification (e.g., 'order=scsi0;net0' or 'order=ide2;scsi0'). If not specified and ISO is provided, defaults to booting from CD-ROM first.	string	null	no
bridge	Network bridge to attach NICs to (e.g., vmbr0)	string	"vmbr0"	no
cipassword	Cloud-init user password. Not required when ISO is specified.	string	null	no
ciuser	Cloud-init default user. Not required when ISO is specified.	string	null	no
clone	Source template or VM name to clone. Not required when ISO is specified.	string	null	no
cores	DEPRECATED: use the cpu block or instance_size instead. CPU cores per socket.	number	null	no
cpu	Explicit CPU configuration (overrides cores/sockets/vcpus variables)	object({ cores = number sockets = number vcores = number })	null	no
id	NIC device ID/index as required by the provider	number	0	no
instance_size	Preset size key (xsmall, small, medium, large, xlarge). Empty to use custom values	string	""	no
instance_sizes	Map of size presets defining memory, cores, sockets, vcores, and disk size	map(object({ memory = number cores = number sockets = number vcores = number size = string }))	{ "large": { "cores": 8, "memory": 16384, "size": "40G", "sockets": 1, "vcores": 8 }, "medium": { "cores": 4, "memory": 8192, "size": "20G", "sockets": 1, "vcores": 4 }, "small": { "cores": 2, "memory": 4096, "size": "12G", "sockets": 1, "vcores": 2 }, "xlarge": { "cores": 10, "memory": 32768, "size": "60G", "sockets": 1, "vcores": 10 }, "xsmall": { "cores": 1, "memory": 2048, "size": "10G", "sockets": 1, "vcores": 1 } }	no
ipconfig0	Cloud-init IP config for NIC 0 (e.g., ip=192.168.1.10/24,gw=192.168.1.1). Only ipconfig0 and ipconfig1 are exposed; VMs with more than 2 NICs cannot configure cloud-init IP for NIC 2+.	string	"ip=dhcp"	no
ipconfig1	Cloud-init IP config for NIC 1 (same format as ipconfig0). Maximum supported NIC index for cloud-init is 1.	string	null	no
iso	ISO file location in Proxmox storage format (e.g., 'local:iso/ubuntu-22.04.iso'). When specified, automatically configures IDE2 as a CD-ROM device.	string	null	no
memory	Memory allocated to the VM in MiB	number	null	no
model	NIC model (e.g., virtio, e1000)	string	"virtio"	no
name	VM name as it will appear in Proxmox	string	n/a	yes
nameserver	Default DNS server for the guest	string	null	no
networks	Optional NIC list. If empty, a single NIC is built from bridge/model/tag	list(object({ id = optional(number, 0) model = optional(string, "virtio") bridge = optional(string, "vmbr0") tag = optional(number) firewall = optional(bool) link_down = optional(bool) macaddr = optional(string) queues = optional(number) rate = optional(number) }))	[]	no
notes	Proxmox VM notes (maps to the provider's 'description' resource attribute and the Notes field in the Proxmox UI)	string	"Managed by Terraform."	no
ostype	OS type passed to the provider's os_type attribute. Use 'cloud-init' for cloud-init templates (the default). Other accepted values: ubuntu, centos, fedora, opensuse, arch, debian, alpine, solaris, l24, l26, other, wxp, w2k, w2k3, w2k8, wvista, win7, win8, win10, win11.	string	"cloud-init"	no
pool	Destination Proxmox resource pool	string	null	no
pxe	Enable PXE boot via network interface. When true, sets boot order to network if boot order is not explicitly specified.	bool	null	no
scsihw	SCSI controller model	string	"virtio-scsi-pci"	no
searchdomain	Default DNS search domain suffix	string	null	no
serial0	Serial device index for console access	number	0	no
serial0_type	Serial device type (e.g., 'socket' for a Unix socket, or a host device path like '/dev/ttyS0')	string	"socket"	no
size	Boot disk size (e.g., 20G)	string	null	no
skip_ipv6	Disable IPv6 address reporting from QEMU agent	bool	true	no
sockets	DEPRECATED: use the cpu block or instance_size instead. Number of CPU sockets.	number	null	no
sshkeys	Newline-delimited SSH public keys for the cloud-init user. Not required when ISO is specified.	string	null	no
storage	Proxmox storage target for disks (e.g., local-lvm, nvme2-ceph)	string	n/a	yes
tag	802.1Q VLAN ID	number	null	no
tags	Comma-separated tags stored on the VM	string	""	no
target_node	Preferred Proxmox node to place the VM	string	null	no
target_nodes	List of Proxmox nodes eligible for placement	list(string)	null	no
vcpus	DEPRECATED: use the cpu block or instance_size instead. Total virtual CPUs (threads).	number	null	no
vmid	Proxmox VM ID. Use 0 to auto-assign the next available ID	number	0	no

Outputs

Name	Description
vm_cores	CPU cores per socket as applied by the provider
vm_id	VM ID, parsed from the resource ID to handle auto-assigned VMIDs
vm_ip	Primary IPv4 address reported by the QEMU agent
vm_memory	Memory allocated to the VM in MiB
vm_name	VM name as it appears in Proxmox
vm_nameserver	DNS nameserver configured on the VM
vm_notes	VM notes as stored in Proxmox
vm_sockets	CPU sockets as applied by the provider
vm_tags	Tags stored on the VM
vm_vcpus	vCPUs (vcores) as applied by the provider