Elevating IaC Workflows with Spacelift Stacks and Dependencies 🛠️

Register for the July 23 demo →


How to use Terraform and Proxmox to Deploy a VM

terraform proxmox

In this article, we will take a look at how to use Terraform with Promox to configure a virtual machine. We will show how to install and configure Terraform, set up Proxmox, and show an example configuration, before looking at some common issues you might run into when setting this up.

What we will cover:

  1. What is Proxmox?
  2. How to deploy Proxmox VMs with Terraform?
  3. Common issues and troubleshooting

What is Proxmox?

Proxmox (also known as Proxmox Virtual Environment, Proxmox VE, or PVE) is a virtualization platform based on the Debian Linux distribution that provides a powerful, free, open-source solution for managing virtual machines (VMs) and containers. It utilizes KVM (Kernel-based Virtual Machine) for virtualization and LXC (Linux Containers) for containerization. This combination allows you to run multiple operating systems and applications on a single server. 

Common use cases for Promox include:

  • Running multiple web servers on a single machine
  • Creating development and testing environments
  • Deploying cloud-based applications
  • Consolidating server resources

Proxmox features

Proxmox integrates virtualization (KVM and LXC), software-defined storage, and networking into a unified, web-based interface. The key features of Promox are:

  1. Virtual machine management — Proxmox allows you to create, deploy, and manage VMs.
  2. Container-based virtualization — Containers are lightweight, share the host OS kernel, and provide efficient resource utilization. They are ideal for running applications in isolated environments.
  3. Software-defined storage (SDS) solutions — This feature allows you to manage storage resources efficiently. You can create storage pools, use ZFS, and set up data replication for high availability.
  4. Networking — Proxmox offers features such as virtual LANs (VLANs), bridges, and firewall rules. You can configure network interfaces for VMs and containers.
  5. Clustering support — Proxmox allows you to create a highly available infrastructure.
  6. Proxmox Backup Server — Proxmox Backup Server is an enterprise-grade backup solution that supports incremental backups, deduplication, compression, and encryption.
  7. Proxmox VE — Proxmox VE offers a web-based management interface. It prioritizes security and provides features such as firewall integration, role-based access control (RBAC), and secure communication protocols to protect virtualized environments from unauthorized access and attacks.

Can I use Terraform with Proxmox?

Terraform can be used with Proxmox to deploy and manage virtual machines. Using Terraform with Proxmox offers significant benefits such as automation, infrastructure as code, and consistent deployments. 

However, there may be some limitations due to Proxmox API restrictions and potential issues with certain actions requiring SSH access. Despite these challenges, many users find that the advantages of using Terraform with Proxmox, such as streamlined operations and reduced manual intervention, outweigh the drawbacks when managing their virtualization infrastructure.

How to deploy Proxmox VMs with Terraform?

Deploying Proxmox with Terraform can streamline your virtualization management by automating the creation and configuration of the VMs. In this tutorial section, we walk you through the process, making it easier to leverage the power of both Proxmox and Terraform.

Follow these steps to deploy Proxmox with Terraform:

  1. Install Terraform
  2. Set up Proxmox
  3. Use API keys for authentication
  4. Configure Terraform Proxmox provider
  5. Run Terraform to create the VM
  6. Delete the VM with terraform destroy

1. Install Terraform

First, make sure you have Terraform installed on your system. If not, you can install it on your Linux system using the following commands:

curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
sudo apt-add-repository "deb [arch=$(dpkg --print-architecture)] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
sudo apt update
sudo apt install terraform

You can also download and install it from the official website and see the instructions for installing Terraform on other OSes

2. Set up Proxmox

Next, we are going to need a Proxmox server with API access and user permissions for Terraform.

To set up Proxmox, download the ISO for Proxmox VE from the Promox website.

Create a bootable USB drive (at least 8GB) or burn the ISO to a DVD and boot your server from the media. You can use a tool like BalenaEtcher to flash the downloaded ISO image onto a USB drive.

During the installation process, Proxmox VE provides an intuitive web-based interface for configuration, so there is no need to install separate management tools. 

Proxmox VE is a bare-metal installer, and existing data on the selected disks will be removed, so backup any existing information before proceeding and consider installing to a separate disk. 

The installer will ask you to select the installation disk, set a root password, configure the network, and choose a preferred file system. 

Once Proxmox VE is installed, access the web interface by navigating to https://your-server-ip:8006, and log in using the default credentials (username ‘root’ and password you set during the installation). Once logged in, you can perform initial configuration tasks such as setting up storage, configuring networking, creating virtual machines (VMs), and joining additional Proxmox nodes to form a cluster if needed.

3. Use API keys for authentication

As we want to use Terraform to automate the creation of our Proxmox resources, the next step is to give the Terraform user permission to create a VM using Proxmox.

There are two options for authentication:

  • Username/Password: Use the existing default root user and root password.
  • API Keys: Create a new user (e.g., ‘blog_example’) and generate an API token. The API key method is recommended to avoid storing your root password in Terraform files.

To create a new user and generate an API token:

  1. Go to Datacenter in the left tab.
  2. To create a user for Proxmox Terraform configuration, navigate to Permissions > Users and click Add to create the ‘blog_example’ user.
proxmox terraform example
  1. Under API tokens, create a new token associated with the user. Save this key securely; it won’t be displayed again.
terraform proxmox example

4. Configure Terraform Proxmox provider

Create a Terraform configuration file (e.g., main.tf) that will define the Proxmox provider and your VMs. A Terraform provider is responsible for understanding API interactions and exposing resources. The Proxmox provider uses the Proxmox API. This provider exposes two resources: proxmox_vm_qemu and proxmox_lxc.

In the Terraform code example below, we specify the Proxmox provider and configure the VMs using the proxmox_vm_qemu resource. The full list of available options for this resource can be found on the Terraform provider docs pages.


provider "proxmox" {
 pm_api_url   = "https://your-proxmox-host:8006/api2/json"
 pm_user      = "blog_example"
 pm_password  = "your-api-key"
 pm_tls_insecure = true

resource "proxmox_vm_qemu" "my_vm" {
 name       = "my-vm"
 target_node = "pve"
 clone      = "ubuntu-template"
 storage    = "local-lvm"
 cores      = 2
 memory     = 2048

5. Run Terraform to create the VM

To create the VM, run terraform init to initialize the provider, then terraform plan to view the intended changes, and finally terraform apply.

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Once Terraform has applied the configuration, verify in the Proxmox GUI or using Proxmox command-line tools that the VM has been created with the desired specifications.

6. Delete the VM with terraform destroy

If you want to delete your test VM, simply navigate to the relevant Terraform project directory and run the terraform destroy command.

Common issues and troubleshooting

Like any other software, Proxmox can encounter issues. The table below shows the most common problems and debugging tips for each.

Issue Suggested solutions
Installation boot failure
  • Check if the ISO image is corrupt. Download a fresh copy and reflash the USB drive.
  • Ensure the boot order in your server’s BIOS prioritizes the USB drive containing the Proxmox ISO.
Installation fails during wizard
  • Verify disk space availability. Insufficient space can halt the installation.
  • Double-check your network configuration settings during installation, especially if using a static IP address.
Unable to access the Proxmox web interface or virtual machines are unable to connect to the network
  • Check network configuration settings in Proxmox, including IP addresses, subnet masks, gateways, and DNS servers.
  • Ensure that network interfaces are properly configured and enabled.
  • Verify that firewall settings allow traffic to and from Proxmox services.
“Error: Out of Partition” after fresh install
  • If you encounter this error after installation, it may be due to multiple connected hard drives during installation.
  • Disconnect all but one disk and try again.
Unable to create or access storage resources, such as ZFS pools or Ceph clusters
  • Check storage configuration settings in Proxmox, including storage types, storage pools, and storage devices.
  • Verify that storage devices are properly connected and recognized by Proxmox.
  • Check for any errors or warnings in the Proxmox web interface or logs related to storage.
  • NFS Client Mount Error: “mount.nfs: No such device” — By default, NFS cannot be mounted in VZ containers. Follow the instructions in the OpenVZ: NFS page to set up NFS in containers.
VMs fail to start or encounter errors during operation
  • Check the virtual machine configuration settings, including CPU, memory, disk, and network configurations.
  • Verify that required resources (CPU, memory, storage) are available on the Proxmox host.
  • Check for any errors or warnings in the Proxmox web interface or logs related to VMs.
Authentication and access issues
  • Verify that the correct username and password are being used to log in.
  • Check for any authentication-related errors or warnings in the Proxmox logs.
  • Ensure that network connectivity is available between the client and the Proxmox server.
Proxmox hosts or VMs are experiencing slow performance or high resource utilization
  • Monitor resource utilization using Proxmox tools or external monitoring solutions.
  • Identify any resource bottlenecks, such as CPU, memory, disk, or network congestion.
  • Optimize virtual machine configurations, adjust resource allocations, or scale out the infrastructure as needed.
Unable to upgrade Proxmox VE to a new version or install updates
  • Check for compatibility issues with hardware or third-party software.
  • Review release notes and documentation for known issues and upgrade procedures.
  • Backup critical data and configurations before performing upgrades or updates.

More general assistance can be found here:

  • Consult Proxmox documentation: The Proxmox VE documentation offers extensive troubleshooting guides for various issues.
  • Proxmox forums: The Proxmox forums are a valuable resource where you can find solutions and ask questions from experienced Proxmox users.

Managing Terraform with Spacelift

Spacelift takes managing Terraform to the next level by giving you access to a powerful CI/CD workflow and unlocking features such as:

  • Policies (based on Open Policy Agent) – You can control how many approvals you need for runs, what kind of resources you can create, and what kind of parameters these resources can have, and you can also control the behavior when a pull request is open or merged.
  • Multi-IaC workflows – Combine Terraform with Kubernetes, Ansible, and other IaC tools such as OpenTofu, Pulumi, and CloudFormation,  create dependencies among them, and share outputs
  • Build self-service infrastructure – You can use Blueprints to build self-service infrastructure; simply complete a form to provision infrastructure based on Terraform and other supported tools.
  • Integrations with any third-party tools – You can integrate with your favorite third-party tools and even build policies for them.

Spacelift enables you to create private workers inside your infrastructure, which helps you execute Spacelift-related workflows on your end. For more information on how to configure private workers, you can look into the documentation.

Key points

Proxmox VE is a flexible and feature-rich platform that is suitable for both small-scale and enterprise-level virtualization deployments. Its open-source nature and active community make it a popular choice for organizations looking to build and manage virtualized infrastructure.

You can use a Terraform provider to provision resources on the Proxmox VE platform, automate their creation, and bring all the benefits of infrastructure as code to your deployments.

If you want to elevate your Terraform management, create a free account for Spacelift today or book a demo with one of our engineers.

Note: New versions of Terraform are placed under the BUSL license, but everything created before version 1.5.x stays open-source. OpenTofu is an open-source version of Terraform that expands on Terraform’s existing concepts and offerings. It is a viable alternative to HashiCorp’s Terraform, being forked from Terraform version 1.5.6.

Manage Terraform Better with Spacelift

Build more complex workflows based on Terraform using policy as code, programmatic configuration, context sharing, drift detection, resource visualization and many more.

Start free trial

How can Spacelift stacks & dependencies elevate your IaC workflows?

Don’t miss our July 23 webinar.

Register for the webinar