Provisioning Proxmox VMs with Terraform

Provisioning Proxmox VMs with Terraform involves using a specific Terraform provider (commonly the Telmate or BPG provider) to interact with the Proxmox API. The process typically requires a pre-configured VM template on the Proxmox server and an API token for secure authentication.

Prerequisites :

Proxmox VE Server: A running Proxmox instance with administrative access.
Terraform Installed: Install Terraform on your local machine.
Proxmox VM Template: A base VM template (often a cloud-init image like Ubuntu or Debian) configured with cloud-init support is highly recommended for easy customization.
API Token: Create a dedicated user and API token in Proxmox with the necessary permissions (e.g., VM.Allocate, VM.Clone, Datastore.AllocateSpace) for Terraform to function.

Step-by-Step Guide

1. Set up Proxmox User and API Token

Instead of using the root password, create a dedicated user and API token for security.

In the Proxmox Web GUI, go to Datacenter > Permissions > Users and click Add to create a user (e.g., terraform-prov@pve).
Create a Role with necessary privileges (e.g., TerraformProv) under Datacenter > Permissions > Roles.
Assign the role to the user under Datacenter > Permissions.
Generate an API Token for the user under Datacenter > Permissions > API Tokens. Crucially, copy the generated secret token immediately, as it won’t be shown again.

2. Create Terraform Configuration Files

Create a new directory for your Terraform project and add the following files.

main.tf (Provider Configuration):

This file defines the required provider and how to connect to your Proxmox server. Use environment variables for sensitive data.

hcl

terraform {
  required_providers {
    proxmox = {
      source  = "telmate/proxmox"
      version = "~> 2.9.0" # Use a compatible version
    }
  }
}

provider "proxmox" {
  # These values will be read from environment variables (TF_VAR_pm_api_url, etc.)
  pm_api_url          = var.pve_api_url
  pm_api_token_id     = var.pve_token_id
  pm_api_token_secret = var.pve_token_secret
  pm_tls_insecure     = true # Set to false if you have valid TLS certificates
}

variables.tf (Variable Declarations):

hcl

variable "pve_api_url" {
  description = "Proxmox API Endpoint, e.g. 'https://pve.example.com:8006/api2/json'"
  type        = string
  sensitive   = true
}

variable "pve_token_id" {
  sensitive = true
}

variable "pve_token_secret" {
  sensitive = true
}
# Add other variables like vm_name, target_node, etc. as needed

vm.tf (VM Resource Definition):

This file defines the VM you want to provision, cloning from an existing template.

hcl

resource "proxmox_vm_qemu" "vm_instance" {
  name        = "my-terraform-vm"
  target_node = "pve" # The name of your Proxmox node
  clone       = "ubuntu-template" # Name of your pre-made template
  full_clone  = true
  cores       = 2
  memory      = 2048

  disk {
    size    = "20G"
    type    = "scsi"
    storage = "local-lvm" # Your storage volume name
    discard = "on"
  }

  network {
    model  = "virtio"
    bridge = "vmbr0"
  }

  # Use cloud-init for network/user config
  os_type = "cloud-init"
  ipconfig0 = "ip=dhcp" # or a static IP like "ip=192.168.1.100/24,gw=192.168.1.1"
  sshkeys = "ssh-rsa AAAAB3..." # Your public SSH key for access
}

3. Run Terraform

Set Environment Variables: Before running Terraform commands, set the API credentials as environment variables to avoid hardcoding sensitive information.

bash

export TF_VAR_pve_api_url="https://your_proxmox_ip:8006/api2/json"
export TF_VAR_pve_token_id="your_user@pve!your_token_id"
export TF_VAR_pve_token_secret="your_secret_token_value"

Initialize Terraform: Navigate to your project directory in the terminal and run:
bash
terraform init
This command downloads the Proxmox provider plugin.
Plan the Deployment: Review the changes Terraform will make before applying them:
bash
terraform plan
Apply the Configuration: If the plan looks correct, apply the changes to create the VM(s) in Proxmox:
bash
terraform apply
Type yes when prompted to confirm the operation.

Terraform will now provision the virtual machine on your Proxmox server based on the configuration defined in your files. You can also use terraform destroy later to tear down the resources.