Proxmox VM Terraform Module

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

Features

• Create single or multiple VMs
• Support for cloning from existing templates
• Cloud-init configuration
• Flexible CPU and memory allocation
• Network configuration
• Storage management
• Predefined instance sizes (xsmall, small, medium, large, xlarge)
• NEW (feature/expansion): Multiple network interfaces support
• NEW (feature/expansion): Additional disk configurations

Requirements

Provider Configuration

Usage

Basic Example

module "example_vm" {
  source = "./modules/pvevm"
  
  name         = "example-vm"
  target_node  = "pve-node-1"
  clone        = "ubuntu-template"
  storage      = "local-lvm"
  instance_size = "medium"
  
  # Network configuration
  bridge = "vmbr0"
  model  = "virtio"
  
  # Cloud-init configuration
  ciuser     = "ubuntu"
  cipassword = "your-password"
  sshkeys    = file("~/.ssh/id_rsa.pub")
}

Multiple VMs with for_each

locals {
  vms = {
    web1 = {
      name         = "web-1"
      target_node  = "pve-node-1"
      clone        = "ubuntu-template"
      storage      = "local-lvm"
      instance_size = "small"
      ipconfig0    = "ip=192.168.10.11/24,gw=192.168.10.1"
    }
    db1 = {
      name         = "db-1"
      target_node  = "pve-node-2"
      clone        = "ubuntu-template"
      storage      = "nvme2-ceph"
      instance_size = "medium"
      ipconfig0    = "ip=192.168.10.21/24,gw=192.168.10.1"
    }
  }
}

module "vm" {
  source = "./modules/pvevm"
  for_each = local.vms

  name          = each.value.name
  target_node   = each.value.target_node
  clone         = each.value.clone
  storage       = each.value.storage
  instance_size = each.value.instance_size

  # Optional overrides
  ipconfig0 = try(each.value.ipconfig0, null)
  ipconfig1 = try(each.value.ipconfig1, null)
  networks  = try(each.value.networks, [])
  additional_disks = try(each.value.additional_disks, [])
}

To consume outputs with for_each, access them per key or build a map:

# Per-VM access
module.vm["web1"].vm_id

# Build a map of IDs keyed by VM key
locals {
  vm_ids = { for k, m in module.vm : k => m.vm_id }
}

Inputs

Name	Description	Type	Default	Required
name	The name of the VM within Proxmox	string	n/a	yes
target_node	The name of the Proxmox Node on which to place the VM	string	null	no
clone	The base VM from which to clone to create the new VM	string	n/a	yes
storage	Disk Storage Location	string	n/a	yes
instance_size	The size of the instance (xsmall, small, medium, large, xlarge)	string	""	no
cpu	CPU configuration block	object	null	no
memory	The amount of memory to allocate to the VM in Megabytes	number	null	no
size	Disk Size	string	null	no

Outputs

Name	Description
vm_ip	List of VM IP addresses
vm_name	List of VM names
vm_id	List of VM IDs
vm_vcpus	List of VM vCPU counts
vm_memory	List of VM memory allocations
vm_notes	List of VM descriptions/notes
vm_tags	List of VM tags

Instance Sizes

The module provides predefined instance sizes for quick deployment:

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

Recent Changes

feature/expansion Branch - Multiple Networks and Disks

The feature/expansion branch adds powerful new capabilities:

1. Multiple Network Interfaces

   • Configure VMs with multiple NICs
   • Support for different VLANs per interface
   • Advanced network options (rate limiting, firewall, queues)
   • Backward compatible with single network configuration

2. Additional Disk Support

   • Add multiple additional disks (scsi2-scsi5)
   • Per-disk configuration (SSD, cache, backup, iothread)
   • Flexible storage allocation
   • Primary disk still configured via instance_size

Example:

module "advanced_vm" {
  source = "github.com/valueiron/pvevm.git?ref=feature/expansion"
  
  # ... basic config ...
  
  networks = [
    { bridge = "vmbr0", tag = 100 },  # Management
    { bridge = "vmbr0", tag = 200 }   # Data
  ]
  
  additional_disks = [
    { type = "scsi", slot = 2, storage = "nvme2-ceph", size = "100G", ssd = true },
    { type = "scsi", slot = 3, storage = "local-lvm", size = "500G" }
  ]
}

See examples/multiple-networks-disks.md for detailed examples.

v3.0.2-rc03 Upgrade (main branch)

This module has been updated to use Proxmox provider v3.0.2-rc03 with the following changes:

1. Provider Version: Updated from 3.0.1-rc8 to 3.0.2-rc03
2. Description Field: desc parameter changed to description
3. CPU Configuration: Individual cores, sockets, and vcpus parameters replaced with a cpu block containing:
   • cores: Number of CPU cores per socket
   • sockets: Number of CPU sockets
   • vcores: Total number of virtual CPUs

The module maintains backward compatibility by still supporting the old individual parameters.

License

This module is licensed under the MIT License.

Requirements

Name	Version
terraform	>= 0.13.0
proxmox	3.0.2-rc03

Providers

Name	Version
proxmox	3.0.2-rc03

Modules

No modules.

Resources

Name	Type
proxmox_vm_qemu.pvevm	resource

Inputs

Name	Description	Type	Default	Required
additional_disks	Additional disks to attach (beyond scsi0 boot and cloud-init)	list(object({ type = string # scsi, sata, virtio, ide storage = string # e.g., "local-lvm", "nvme2-ceph" size = string # e.g., "10G", "100G" slot = number # scsi2–scsi5 (slots 0–1 reserved) }))	[]	no
agent	Enable QEMU Guest Agent (1 enabled, 0 disabled)	number	1	no
bridge	Network bridge to attach NICs to (e.g., vmbr0)	string	"vmbr0"	no
cipassword	Cloud-init user password	string	n/a	yes
ciuser	Cloud-init default user	string	n/a	yes
clone	Source template or VM name to clone	string	n/a	yes
cores	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)	string	"ip=dhcp"	no
ipconfig1	Cloud-init IP config for NIC 1 (same format as ipconfig0)	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 description/notes	string	"Managed by Terraform."	no
ostype	OS type. Use 'cloud-init' for cloud-init templates	string	"cloud-init"	no
pool	Destination Proxmox resource pool	string	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
size	Boot disk size (e.g., 20G)	string	null	no
sockets	Number of CPU sockets	number	null	no
sshkeys	Newline-delimited SSH public keys for the cloud-init user	string	n/a	yes
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	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_id	VM ID
vm_ip	VM IPv4 Address
vm_memory	VM Memory
vm_name	VM Name
vm_nameserver	VM Nameserver
vm_notes	VM Notes
vm_tags	VM Tags
vm_vcpus	VM VCPUS