Clone Proxmox VMs with Terraform

With the help of Terraform's IaC solution, you can easily clone Proxmox VMs. In this post, you'll learn about the Terraform Proxmox provider, how to generate an API token, how to create the Terraform files, and finally, how to clone VMs.

Author
Recent Posts

Brandon Lee

Brandon Lee has been in the IT industry 15+ years and focuses on networking and virtualization. He contributes to the community through various blog posts and technical documentation primarily at Virtualizationhowto.com.

What is Proxmox?

Proxmox is a superb option for a free hypervisor with many features. It provides an easy way to run virtual machines and LXC containers in your environment. It also features an API that can be easily automated using tools such as Terraform. It runs virtual machines on top of the kernel virtual machine (KVM) hypervisor in Linux. It also combines the capabilities of LXC containers in the platform, allowing you to run Linux containers efficiently in your environment.

What is Terraform?

Terraform is a well-known infrastructure-as-code offering that enables DevOps engineers and admins to deploy infrastructure reliably and in an automated way. Terraform uses providers to connect to infrastructure and describe it in the HashiCorp Configuration Language (HCL). For example, using Terraform and the Proxmox provider, we can connect to Proxmox and perform automation in our Proxmox environment.

Terraform Proxmox provider

The Terraform provider for Proxmox speaks directly with the Proxmox API and exposes a couple of resources that we can use to create Proxmox VM and LXC container resources.

proxmox_vm_qemu
proxmox_lxc

You can view the official documentation from the Terraform registry here: Docs overview | Telmate/proxmox | Terraform Registry

proxmox_vm_qemu resource

The VM Qemu resource manages your Proxmox VM resources. With Terraform, you need a starting point to provision Proxmox virtual machines, including an ISO, a PXE boot, and a VM. Alternatively, you can clone an existing Proxmox template. Once you have determined the source of your virtual machine creation, you can use the proxmox_vm_qemu resource configuration block to create new VM resources.

proxmox_lxc resource

The promxox_lxc Terraform resource allows you to create and manage Proxmox LXC containers. Since the containers are pulled from the cloud repository, there is no prerequisite for having a local source.

Generate an API token

The first step in interacting with Proxmox programmatically is to generate an API token for authentication. The API token eliminates the need to log in with a username and password. Suppose you want to have only the permissions needed for Terraform to interact with your Proxmox environment. In this case, HashiCorp gives an example of a role with the necessary permissions for Terraform operations.

pveum role add TerraformProv -privs "Datastore.AllocateSpace Datastore.Audit Pool.Allocate Sys.Audit VM.Allocate VM.Audit VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.Monitor VM.PowerMgmt"

You will assign the above permissions to the user you want to use for Terraform. After you have created your user and assigned the role, create the API token needed for access.

Adding a new user API token for Terraform

Copy the API token secret and store it somewhere safe, as you will need it for your Terraform configuration.

Copy the secret value for the API token

Uncheck the Privilege Separation checkbox.

Uncheck the Privilege Separation checkbox

Creating Terraform files

Now that we have Terraform access configured, we can begin building the Terraform files for automation. We will create three files:

variables.tf
terraform.tfvars
main.tf

In this example, we will clone an existing VM template to create a new virtual machine in Proxmox.

variables.tf

The variables.tf file will house the variables used for Terraform automation. The following variables will be used for the Proxmox URL, token ID, and token secret.

variable "pm_api_url" {
  type = string
}
variable "pm_api_token_id" {
  type = string
}
variable "pm_api_token_secret" {
  type      = string
  sensitive = true
}

The variables.tf file used for Terraform automation

terraform.tfvars

In the terraform.tfvars file, we set the values for the variables we defined in the variables.tf file. You will define the values for the API, token_id, and token_secret.

pm_api_url = "<your Proxmox API URL>"
pm_api_token_id = "<your token>"
pm_api_token_secret = "< your token secret>"

Configuring terraform.tfvars

main.tf

We place our code for performing declarative operations in Terraform in main.tf.

terraform {
  required_providers {
    proxmox = {
      source = "telmate/proxmox"
    }
  }
}

provider "proxmox" {
  pm_api_url = "https://10.1.149.74:8006/api2/json"
}

resource "proxmox_vm_qemu" "test-clone" {
  name        = "VM-test"
  desc        = "Clone demo"
  target_node = "proxmox"
  

  ### or for a Clone VM operation
  clone = "clonesource"
  cores = 1
  sockets = 1
}

Main.tf configuration for Proxmox

Cloning Proxmox VMs

The workflow for running Terraform is as follows:

terraform init—Terraform init will pull the required provider
terraform plan—Terraform plan will verify the operations to perform and check the syntax
terraform apply—Terraform apply will the planned changes

Below, we run the terraform init command.

Performing a terraform init for the Proxmox provider

Next, terraform plan.

Performing a terraform plan

Finally, we run the terraform apply command to apply the Terraform configuration.

Performing a terraform apply and validating the operation

As expected, the Terraform apply operation should kick off and create the new virtual machine from the VM clone.

Subscribe to 4sysops newsletter!

The terraform apply completes successfully

Wrapping up

Proxmox and Terraform are excellent free, open-source tools for effective virtualization in a home lab or production environment. Using Terraform automation to clone an existing Proxmox VM and create a new virtual machine works well, as shown.