Deploying Ubuntu VM in Proxmox using Terraform

To deploy to Proxmox using Terraform, you can follow these steps:

Setting up your Terraform environment

  • Download the Terraform binary for your operating system from the official Terraform website:
  • Extract the downloaded archive.
  • Move the Terraform binary to a directory included in your system’s PATH environment variable. This ensures you can run the terraform command from any location in your terminal or command prompt.

Alternatively for windows user, you can use chocolatey to install terraform.

Verify the installation by using terraform version

If the command displays the Terraform version, then the installation was successful.

Now comes the fun part.

Create a folder and give it any name, in my case I would call it proxmox-terraform-sample

Under this folder create the following empty files

First we are required to install a provider that will help us connect to proxmox and create the VM. Telemate/Promox creates a provider that we will be using today.

Add the following line in the and run command terraform init

terraform {
  required_providers {
    proxmox = {
      source  = "telmate/proxmox"
      version = ">=2.9.14"

If successful, you will see the following message

Initializing the backend...

Initializing provider plugins...
- Finding telmate/proxmox versions matching ">= 2.9.14"...
- Installing telmate/proxmox v2.9.14...
- Installed telmate/proxmox v2.9.14 (self-signed, key ID A9EBBE091B35AFCE)

Partner and community providers are signed by their developers.
If you'd like to know more about provider signing, you can read about it here:

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

The provided Terraform code is used to define and provision a virtual machine (VM) on a Proxmox server.

provider "proxmox" {
  pm_api_url          = var.api_url
  pm_api_token_id     = var.token_id
  pm_api_token_secret = var.token_secret
  pm_tls_insecure     = true

resource "proxmox_vm_qemu" "test_server" {
  define_connection_info = false
  agent                  = 1
  count                  = 1
  name                   = "test-vm-${count.index + 1}"
  target_node            = var.proxmox_host
  iso                    = "local:iso/ubuntu-22.04.1-live-server-amd64.iso"

  # basic VM settings
  cores   = 2
  sockets = 1
  cpu     = "host"
  memory  = 2048
  os_type = "ubuntu"

  disk {
    size    = "10G"
    type    = "scsi"
    storage = "local-lvm"

  network {
    model  = "virtio"
    bridge = var.nic_name

  lifecycle {
    ignore_changes = [

Let’s break down the code to understand its functionality:

  1. The provider block configures the Proxmox provider. It specifies the necessary connection information such as the API URL (pm_api_url), token ID (pm_api_token_id), and token secret (pm_api_token_secret). Additionally, pm_tls_insecure is set to true to disable SSL certificate validation.
  2. The resource block defines a Proxmox VM resource named “test_server” using the proxmox_vm_qemu resource type. It provisions a QEMU-based virtual machine.
  • define_connection_info is set to false, indicating that Terraform should not configure SSH connection information for the VM.
  • agent is set to 1, enabling the Proxmox guest agent inside the VM.
  • count is set to 1, indicating that a single instance of the VM should be created.
  • name specifies the name of the VM as “test-vm-1” (count.index starts from 0, so count.index + 1 gives a sequential number).
  • target_node is set to the value of the proxmox_host variable, which represents the Proxmox host on which the VM will be deployed.
  • iso specifies the ISO image to be used for the VM’s installation. In this case, it references a local ISO file: “iso/ubuntu-22.04.1-live-server-amd64.iso”. The subsequent configuration options define various settings for the VM, including:
  • cores and sockets represent the number of CPU cores and sockets to allocate to the VM.
  • cpu is set to “host,” allowing the VM to leverage the CPU capabilities of the host machine.
  • memory specifies the amount of memory (in MB) to allocate to the VM.
  • os_type specifies the operating system type as “ubuntu”. Inside the disk block, a virtual disk is defined for the VM with a size of “10G”, using the “scsi” type and storing it on the “local-lvm” storage. Inside the network block, the network configuration for the VM is specified. It uses the “virtio” model and bridges the VM’s network interface to the value of the nic_name variable. Finally, the lifecycle block is used to configure lifecycle behavior. In this case, it specifies that changes to the network and vmid attributes should be ignored, meaning Terraform will not attempt to update those values if they change outside of Terraform’s control.

Overall, this Terraform code defines a single Proxmox virtual machine with specific hardware and network configurations, along with a defined ISO image for installation.