Provision Proxmox VMs quickly and easily with Terraform (2023)

Update: We have uploaded an update to this article with Terraform 1.0. You can find it here:Terraform 1 and Proxmox; works as it should

Previously I wrote an article about deploying Proxmox VMs with Ansible, you can find itHere.

This article looked at how a functional Ansible script works, which provisions Proxmox virtual machines in a simple and streamlined way and can be integrated into many other implementations.

This time we're going to look at Terraform with a different possibility.

Terraform allows us to streamline the process even further by using plugins, much like Ansible would do.

Both methods depend on a template to be created beforehand. You could of course just create an empty virtual machine and it would work, but that means you have to do the OS installation manually, where's the fun in that?

Inside Proxmox, the VM creation method is (using the GUI):

Create VM -> Present OS ISO on VM -> Perform installation -> Enjoy

This process takes too long, is manual (eww) and frankly it's just plain boring. Especially if you need to create multiple VMs.

Let's create a template for Terraform to use.

Creating a template

Within Proxmox you can (usually) choose two ways to create a VM, via the GUI or via the terminal console. For this example, you should use a machine with the bare minimum and the minimum resources allocated to it. This way it can be easily scaled in the future.

You need a VM with the following resources:

1 Kern
1 GB of memory
10GB hard drive
1 network interface
1 cloud init drive
1 EFI hard drive

(Video) Tutorial: How to deploy VMs in Proxmox using Terraform

Some of the above properties need to be added after the VM creation process.

Creating the template manually

The process of creating a VM within the Proxmox GUI has been explained countless times on the internet. For the sake of completeness, we mention the basic process:

1) Click Create VM
2) Enter a name for the VM, you can check if it starts on boot, your call. Click next
3) Choose an ISO to install and select the type and version of the operating system to install. Click next
4) Enable the "Qemu Agent" option, you will use this later. Click next
5) Select the disk size, in this case 10GB. You can also change some of the storage emulation options for that drive, we won't go into that in this example. Click next
6) Select how many cores you want to use for the VM, in this case 1 core. Click next
7) Enter the amount of memory for the VM, in this case 1024 MB. I recommend using the ballooning device so you can save memory resources on the node and oversell the resources just like you would with a CPU. Note that if the memory is actually used by the VM, it cannot be used by other VMs unless they are in the exact same block of memory. Enter KSM (Kernel Shared Memory) Impressive. Select the minimum memory for the ballooning device, in this case 256MB. Click next
8) If you don't have any custom network configurations on the node, you can just click Next here. In this case, make sure that the configuration meets your requirements.
9) Confirm VM setup and click FinishDo not start the VM yet

After the VM is created, you need to change a few things on the VM. As you can see from the steps above, the cloud-init drive has not been added. Select the VM on the left and click Hardware, then Add, and finally Cloud-Init Drive and select the storage where you want it to reside.

Then edit the BIOS (double click on the BIOS entry under the Hardware tab) and select OVMF (UEFI)

Finally the EFI disk, it's the same process as the cloudinit drive, but now select EFI disk and the storage where it will reside. You cannot create the drive before setting up the BIOS in the second step.

In the VM's terminal, you can go ahead and install the packages from cloud-init so the VM is ready to use with:

apt-get install cloud-init -y

Using Debian's official image for cloud-init.

If the manual process above is taking too long and you don't want to spend so much time installing the operating system, you can simply download a preconfigured image from the official Debian repositories.

In the terminal of the proxmox node, run:

wget https://cdimage.debian.org/cdimage/openstack/current-10/debian-10-openstack-amd64.qcow2

Since we have described the process through GUI in manual installation, let's go to CLI method, the commands are as follows:

qm create 9000 -name debian-10-template -memory 1024 -net0 virtio,bridge=vmbr0 -cores 1 -sockets 1 -cpu cputype=kvm64 -description "Debian 10 cloud image" -kvm 1 -numa 1qm importdisk 9000 debian-10 -openstack-amd64.qcow2 lvm-thinqm set 9000 -scsihw virtio-scsi-pci -virtio0 lvm-thin:vm-9000-disk-1qm set 9000 -serial0 socketqm set 9000 -boot c -bootdisk virtio0qm set 9000 -agent 1qm set 9000 -hotplug disk,network,usb,memory,cpuqm set 9000 -vcpus 1qm set 9000 -vga qxlqm set 9000 -name debian-10-templateqm set 9000 -ide2 lvm-thin:cloudinitqm set 9000 -sshkey /etc/pve/pub_keys /pub_key.pub

Please, please, please consider that the disk needs to be resized to 10GB in order for the VM to have space to grow while running. You can do this from the "Hardware" tab in the GUI.

template setup

Ok, you've created the template, now what?

The template must contain some packages to work smoothly. Not all of these packages are essential, but I usually opt for:

sudo apt install bmon screen ntpdate vim locales-all iotop auf curl libpam-systemd python-pip python-dev ifenslave vlan mysql-client sysstat snmpd sudo lynx rsync nfs-common tcpdump strace darkstat qemu-guest-agent

Define template

When the VM has been shut down cleanly you can go ahead and convert it to a template, this can be done on the Proxmox GUI by right clicking on the VM and clicking "Convert to Template".

In this case we rename the VM template to:debian-cloudinit

Success, the template has been created.

Enter Terraform

Terraform works pretty simply.

It uses an HCL format file (similar to JSON) which is JSON compatible.

Within this file (or files) you can define a complete infrastructure. How simple or complex it can be is up to you. For this example it's going to be a fairly simple infrastructure definition, after all we're just creating a VM (for now).

Terraform installation has been explained countless times online for whatever operating system you're using, so I assume you know how to install it (or how to google: terraform install<insert operating system here>).

After installation, you need to install a provider so that it can communicate with the Proxmox API server. Fortunately, there is a provider that is actively being developed for this use.

Proxmox Vendor

You can find the Proxmox provider for TerraformHere.

The project is under active development and runs without problems most of the time (99% of the time always works).

To install it, just run the following commands to install the dependencies:

go get -v github.com/Telmate/terraform-provider-proxmox/cmd/terraform-provider-proxmoxgo get -v github.com/Telmate/terraform-provider-proxmox/cmd/terraform-provider-proxmoxgo install -v github. com/Telmate/terraform-provider-proxmox/cmd/terraform-provider-proxmoxgo install -v github.com/Telmate/terraform-provider-proxmox/cmd/terraform-provider-proxmoxmake

Finally, copy the executables that the compilation gave us to the path directory, in my case:

sudo cp $GOPATH/bin/terraform-provider-proxmox /usr/local/bin/ sudo cp $GOPATH/bin/terraform-provider-proxmox /usr/local/bin/

Terraform Project

Now you can start with the Terraform project and the project definitions.
We will use a directory structure like this:

tfProxmox|-main.tf

Just a single file. Remember this can be as complex or as simple as you need it to be.

project definition

Darinmain.tffile, you must first set up the connection profile for the Proxmox node. If you have a cluster, any of the nodes will do:

Anbieter "proxmox" { pm_api_url = "https://$PROXMOXSERVERIP:8006/api2/json" pm_user = "[Email Protected]" pm_password = "$SUPERSECRETPASSWORD" pm_tls_insecure = "true"}

Remember to change the $PROXMOXSERVERIP and $SUPERSECRETPASSWORD variables in the example.

SSH key

Since you're using a cloud-init image (if you've opted for Debian's official template image), it's set up for passwordless login, so you need to define an SSH key to install on the VM:

variable "ssh_key" { default = "#INSERTSSHHPUBLICKEYHERE"}

Wo$INSERTSSHHPUBLICKEYHIERis the public SSH key of your Super Amazing laptop.

Now you can define the VM yourself.

VM-Definition

Below these definitions, we can start defining our VM:

Ressource "proxmox_vm_qemu" "proxmox_vm" { count = 1 name = "tf-vm-${count.index}" target_node = "$NODETOBEDEPLOYED"clone = "debian-cloudinit"os_type = "cloud-init" cores = 4 sockets = "1" cpu = "host" memory = 2048 scsihw = "virtio-scsi-pci" bootdisk = "scsi0"disk { id = 0 size = 20 type = "scsi" storage = "data2" storage_type = "lvm" iothread = true }network { id = 0 model = "virtio" bridge = "vmbr0" }lifecycle {ignore_changes = [ network, ] }# Cloud Init Settings ipconfig0 = "ip=10.10.10.15${count.index + 1}/24, gw=10.10.10.1"sshkeys = <<EOF ${var.ssh_key} EOF}

Remember to change those$NODETOBEDEPLOYEDEntry for the node name on which the VM is deployed and thelvm-thinAccess to the storage resource you are using.

Let's explain the resource definition. The main entries to consider are:

count <- This specifies the number of VMs to create name <- This specifies the VM name, "${count.index}" allows you to create more than one VM and it only counts from there, e.g. E.g.: tf-vm -1, tf-vm-2, tf-vm-3 etc. Cores <- The number of cores the VM will have Memory <- The amount of RAM the VM will have Disk < - The disk definitions for the VM, scale the size here.network <- The network bridge definition to use.ipconfig0 <- The IP for the VM, the "${count.index}" allows you to have more than one VM to create and it is only counted from then on, e.g. 10.10.10.151, 10.10.10.152, etc.

Running Terraform

Terraform uses 3 main phases to run:

• Init - This step allows Terraform to initialize and download the required plugins to run
• Plan - This step performs the planning for the deployment using the tf file you defined. It focuses on the calculation for deployment and conflict resolution, if there is such a conflict, it shows you all the changes, additions and deletions that need to be done.
• Apply - After the planning phase, this is the phase where the changes are applied to the infrastructure. It will provide you with a summary of the changes, additions and/or deletions to be made and ask you to confirm that you accept those changes.

inside

In the project folder, run:

Terraform-Init

As already mentioned, Terraform will be initialized and the required plugins for the project will be installed. The output should look like this:

terraform initInitializing backend...Initializing provider plugins...Terraform has been successfully initialized!You can now start working with Terraform. Try running terraform plan to see any changes required by your infrastructure. All Terraform commands should now work. If you ever set or change modules or the backend configuration for Terraform, run this command again to reinitialize your working directory. If you forget this, other commands will recognize it and remind you if necessary.

The plan

This step takes care of any calculations that need to be performed and resolving any conflicts with the infrastructure that may already be deployed.

[Email Protected]:~$ terraform planRefreshing Terraform state in-memory before plan...The updated state is used to compute this plan, but is not persisted in local or remote state storage.------------ --- ------------------------------------------------ --- -------An execution plan has been generated and is shown below. Resource actions are indicated with the following icons: + createTerraform performs the following actions: # creating proxmox_vm_qemu.proxmox_vm[0] + resource "proxmox_vm_qemu" "proxmox_vm" { + agent = 0 + balloon = 0 + boot = "cdn" + bootdisk = "scsi0" + clone = "debian-cloudinit" + clone_wait = 15 + cores = 4 + cpu = "host" + force_create = false + full_clone = true + hotplug = "network,disk,usb" + id = (known after apply) + ipconfig0 = "ip=10.10.10.151/24,gw=10.10.10.1" + memory = 2028 + name = "tf-vm-0" + numa = false + onboot = true + os_type = "cloud-init" + preprovision = true + scsihw = "virtio-scsi-pci" + sockets = 1 + ssh_host = (known after apply) + ssh_port = (known after apply) + sshkeys = <<~EOT ssh-rsa ... EOT + target_node = "pmx-01" + vcpus = 0 + vlan = -1+ disk { + backup = false + cache = "none" + format = "raw" + id = 0 + iothread = true + mbps = 0 + mbps_rd = 0 + mbps_rd_max = 0 + mbps_wr = 0 + mbps_wr_max = 0 + replica = false + size = "20" + st orage = "data2 " + storage_type = "lvm" + type = "scsi" }+ network { + bridge = "vmbr0" + firewall = false + id = 0 + link_down = false + model = "virtio" + queues = -1 + rate = - 1 + tag = -1 } }Plan: 1 to add, 0 to change, 0 to destroy. ----------------------------------------------------------This plan was saved under: planfileTo perform exactly these actions, run the following apply command: terraform apply "planfile"

The plan says that a new resource will be created on the target node: pmx-01 (that's the node I use in my lab).

After you've reviewed the plan and everything seems fine, apply it.

Use

To apply the Terraform plan, simply run:

apply terraform

This will give you the summary of the plan and ask you to confirm. Type in: Yes and it will place its bid.

When it's done, the output should look like this:

[Email Protected]:~$ terraform apply.........ye........Apply complete! Resources: 1 added, 0 changed, 0 destroyed. The state of your infrastructure has been saved in the path below. This state is required to modify and destroy your infrastructure, so keep it safe. To check the full state, use the terraform show command. State path: terraform.tfstate

Final Thoughts

This example should serve as a starting point for Terraform to interact with Proxmox.

Take into account that you can destroy the VM by changing the number tomain.tfZero out the file and go through the planning and application phases.

You can share those toomain.tfFile into different files so it's more organized if you decide to expand the infrastructure with different machine role definitions and different configurations for each of them.

I also uploaded the file to my GitHubHereif you just want the file.

Thank you for reading.

New additions

As some people have reported, there might be some problems installing the proxmox plugin on their machines.

I have a Docker image set up and ready for it. The repo is located at:

https://github.com/galdorork/terragrunt-proxmox-provisioner

And here is the link to the image in Docker's public registry:

https://hub.docker.com/r/galdor1/terragrunt-proxmox-provisioner