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:
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:
- Virtual machine management — Proxmox allows you to create, deploy, and manage VMs.
- 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.
- 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.
- Networking — Proxmox offers features such as virtual LANs (VLANs), bridges, and firewall rules. You can configure network interfaces for VMs and containers.
- Clustering support — Proxmox allows you to create a highly available infrastructure.
- Proxmox Backup Server — Proxmox Backup Server is an enterprise-grade backup solution that supports incremental backups, deduplication, compression, and encryption.
- 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.
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:
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.
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.
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:
- Go to Datacenter in the left tab.
- To create a user for Proxmox Terraform configuration, navigate to Permissions > Users and click Add to create the ‘blog_example’ user.
- Under API tokens, create a new token associated with the user. Save this key securely; it won’t be displayed again.
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.
main.tf
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
}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.
If you want to delete your test VM, simply navigate to the relevant Terraform project directory and run the terraform destroy command.
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 |
|
| Installation fails during wizard |
|
| Unable to access the Proxmox web interface or virtual machines are unable to connect to the network |
|
| “Error: Out of Partition” after fresh install |
|
| Unable to create or access storage resources, such as ZFS pools or Ceph clusters |
|
| VMs fail to start or encounter errors during operation |
|
| Authentication and access issues |
|
| Proxmox hosts or VMs are experiencing slow performance or high resource utilization |
|
| Unable to upgrade Proxmox VE to a new version or install 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.
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.
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.
