Proxmox VE Virtual Machine Terraform Module

This Terraform module simplifies the provisioning and management of multiple Virtual Machines on Proxmox VE using the bpg/proxmox provider.

It supports bulk VM creation, customizable default settings across all VMs, and dynamic Cloud-Init configuration via custom user data snippets.

Features

• Bulk VM Management: Define multiple VMs in a single map (machines).
• Default Inheritance: Set global default settings (defaults) for CPU, RAM, disk size, disk datastore, cloud-init user, etc., which can be selectively overridden per VM.
• Cloud-Init Snippets: Automatically generates custom Cloud-Init YAML snippets (templates/ci.yaml) for each VM.
• Cloud-Init Customizations: Configure hostname, user account, password, SSH authorized keys, system packages, and custom run commands.
• QEMU Guest Agent: Automatically enables and starts the QEMU Guest Agent inside the VM.

Requirements

Name	Version
Terraform	>= 0.13
Proxmox Provider	bpg/proxmox

Usage Example

terraform {
  required_providers {
    proxmox = {
      source  = "bpg/proxmox"
      version = "~> 0.93.0"
    }
  }
}

provider "proxmox" {
  endpoint = "https://proxmox.example.com:8006/"
  username = "terraform@pam!terraform"
  insecure = true

  ssh {
    agent       = true
    username    = "root"
    private_key = file("~/.ssh/id_ed25519")
  }
}

resource "proxmox_virtual_environment_pool" "cluster" {
  comment = "Managed by Terraform"
  pool_id = "cluster"
}

data "proxmox_virtual_environment_file" "debian13" {
  node_name    = "pve-node-1"
  datastore_id = "local"
  content_type = "import"
  file_name    = "debian-13-genericcloud-amd64.qcow2"
}

module "proxmox_vms" {
  source = "git::https://gitlab.example.com/terraform/pve-cluster.git"

  node_name           = "pve-node-1"
  pool_id             = proxmox_virtual_environment_pool.cluster.id
  datastore_id_for_ci = "local"

  # Global default settings applied to all machines unless overridden
  defaults = {
    cpu               = 2
    ram               = 2048
    disk_size         = 32
    disk_datastore_id = "local-lvm"
    image             = data.proxmox_virtual_environment_file.debian13.id
    ci_user           = "sysadmin"
    ci_password       = "SecretPassword"
    ci_timezone       = "Europe/Prague"
  }

  # Map of machines to provision
  machines = {
    web-server = {
      cpu         = 4
      ram         = 4096
      ci_packages = ["nginx", "htop"]
      ci_run_cmds = ["systemctl enable --now nginx"]
    }

    db-server = {
      ram         = 8192
      disk_size   = 100
      ci_ssh_keys = [file("~/.ssh/id_ed25519.pub")]
    }
  }
}

output "vm_info" {
  value = [
    for vm in module.proxmox_vms.virtual_machines : {
      id   = vm.id
      name = vm.name
      ip   = try(vm.ipv4_addresses[1][0], "N/A")
    }
  ]
}

Inputs

Name	Description	Type	Default	Required
node_name	Name of the Proxmox target node.	string	n/a	yes
pool_id	Resource pool ID to assign the VMs to.	string	n/a	yes
datastore_id_for_ci	Proxmox datastore ID where Cloud-Init snippets are stored.	string	"local"	no
defaults	Default configuration settings for all VMs.	object	{}	no
machines	Map of VM definitions. Override any default values per VM.	map(object)	n/a	yes

Defaults Object Structure

Key	Description	Type	Default
image	Path/ID of the OS image to import.	string	null
cpu	Number of CPU cores.	number	1
ram	Dedicated and floating RAM in MB.	number	1024
disk_datastore_id	Target datastore for the VM disk.	string	"local-lvm"
disk_interface	Disk bus/interface type.	string	"virtio0"
disk_size	Disk size in GB.	number	16
init_datastore_id	Datastore ID for Cloud-Init initialization volume.	string	"local-lvm"
network_bridge	Network bridge name.	string	"vmbr0"
ci_timezone	Timezone setting for Cloud-Init.	string	"Europe/Prague"
ci_hostname	Hostname override (defaults to VM name if null).	string	null
ci_user	Default Cloud-Init user account name.	string	"user"
ci_password	Plaintext password for Cloud-Init user.	string	null
ci_ssh_keys	Set of SSH public keys for Cloud-Init user.	set(string)	[]
ci_packages	Additional APT/system packages to install.	set(string)	[]
ci_run_cmds	Commands to execute via Cloud-Init runcmd.	set(string)	[]

Outputs

Name	Description
virtual_machines	Map of created proxmox_virtual_environment_vm resources.
cloud_init_configs	Map of created proxmox_virtual_environment_file Cloud-Init snippet resources.