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

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)	[]
ci_ssh_pwauth	Enables SSH password auth; defaults to true when no SSH keys are provided.	bool	null

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.