Terraform Proxmox Provider: How to Deploy a VM

In this article, we’ll show you how to use Terraform with Proxmox to deploy and manage virtual machines using the bpg provider, the actively maintained community standard. We’ll cover why you’d choose Terraform over the Proxmox GUI, how to choose the right provider, walk through a complete setup from installation to VM creation, and cover common issues you might run into along the way.

What we will cover:

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

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.

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.

Why should I use Terraform with Proxmox instead of the GUI?

The Proxmox web interface is great for getting started, but it doesn’t scale well. Every VM you create manually is a configuration that lives only in Proxmox. This is hard to reproduce, impossible to version, and tedious to repeat.

Terraform solves this by treating your infrastructure as code. The main benefits:

• Reproducibility — Your VM configuration is a .tf file you can reuse across nodes, environments, and team members.
• Version control — Store configs in Git and get a full audit trail of every change, with the ability to roll back.
• Automation — Integrate with CI/CD pipelines to provision and destroy environments automatically.
• Scale — Changing a count and running terraform apply is far faster than clicking through the GUI 30 times.

The GUI still has its place for one-off tasks and monitoring. Most teams end up using both: Terraform for provisioning, the GUI for day-to-day management.

Which Terraform Proxmox provider should I use: Telmate or bpg?

There are two main community providers for Proxmox, and it’s worth understanding what each one offers before choosing.

• telmate/proxmox — The original Terraform provider for Proxmox, covering the core use cases of VM provisioning (proxmox_vm_qemu), LXC containers, and resource pools. Widely referenced in older tutorials, though its latest release remains a release candidate (v3.0.2-rc07) and its scope is intentionally limited to 5 resources.
• bpg/proxmox — A comprehensive, actively maintained provider currently at v0.101.0, with 111 resources and 87 data sources spanning VMs, LXC containers, networking (VLANs, bridges, SDN), storage (NFS, ZFS, PBS, LVM), firewalls, high availability, and backup jobs. The recommended choice for new projects.

For new projects, bpg is the recommended choice. Telmate remains a reasonable option if you’re maintaining an existing configuration and the limited resource coverage meets your needs, but for anything beyond basic VM provisioning, bpg is the more capable and future-proof provider.

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

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. 

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:

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.

3. Under API tokens, create a new token associated with the user. Save this key securely; it won’t be displayed again.

Once you have the token, the value for the api_token argument in the provider config is assembled from three parts: the username, the realm, the token name, and the token secret — in the format user@realm!token-name=token-secret. 

For example, if your user is blog_example in the pam realm with a token named terraform, it would look like: blog_example@pam!terraform=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

First, add a required_providers block to declare the bpg provider source and version:

terraform {
  required_providers {
    proxmox = {
      source  = "bpg/proxmox"
      version = "~> 0.101"
    }
  }
}

Then configure the provider with your Proxmox endpoint and API token. The token follows the format user@realm!token-name=token-secret and can be generated in Datacenter > API Tokens in the Proxmox UI. To avoid storing credentials in your Terraform files, you can pass the token via the PROXMOX_VE_API_TOKEN environment variable instead.

provider "proxmox" {
  endpoint  = "https://your-proxmox-host:8006/"
  api_token = "blog_example@pam!terraform=your-api-token-secret"
  insecure  = true # set to false if using a valid TLS certificate
}

Create a proxmox_virtual_environment_vm resource to define your virtual machine. The example below clones from an existing template, configures CPU and memory, and attaches a disk and network interface:

resource "proxmox_virtual_environment_vm" "my_vm" {
  name      = "my-vm"
  node_name = "pve"

  clone {
    vm_id = 100 # replace with the numeric ID of your template VM in Proxmox
  }

  cpu {
    cores = 2
  }

  memory {
    dedicated = 2048
  }

  disk {
    datastore_id = "local-lvm"
    interface    = "scsi0"
  }

  network_device {
    bridge = "vmbr0"
  }
}

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	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.

Spacelift takes managing Terraform to the next level by giving you access to a powerful infrastructure orchestration 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. You can also control the behavior when a pull request is open or merged.
• Multi-IaC workflows — Combine Terraform with Kubernetes, Ansible, and other infrastructure as code 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 also 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.