Repository files navigation

A Terraform / OpenTofu Provider that adds support for Proxmox Virtual Environment.

This repository is a fork ofhttps://github.com/danitso/terraform-provider-proxmox which is no longer maintained.

This project is a personal open-source initiative and is not affiliated with, endorsed by, or associated with any of my current or former employers. All opinions, code, and documentation are solely those of myself and the individual contributors.

The project is not affiliated withProxmox Server Solutions GmbH or any of its subsidiaries. The use of the Proxmox name and/or logo is for informational purposes only and does not imply any endorsement or affiliation with the Proxmox project.

This provider is compatible with Proxmox VE 9.x (currently9.0). SeeKnown Issues below for compatibility details.

While the provider is on version 0.x, it is not guaranteed to be backward compatible with all previous minor versions.However, we will try to maintain backward compatibility between provider versions as much as possible.

• Proxmox Virtual Environment 9.x
• TLS 1.3 for the Proxmox API endpoint (legacy TLS 1.2 is optionally supported)
• Terraform 1.5+ orOpenTofu 1.6+

• Go 1.25 (to build the provider plugin)
• Docker (optional, for running dev tools)

You can find the latest release and its documentation in theTerraform Registry orOpenTofu Registry.

For manual provider installation, you can download the binaries from theReleases page.You also can usegh tool to verify the binaries provenance, see more detailshere.

To test the provider, simply runmake test.

maketest

Tests are limited to regression tests, ensuring backward compatibility.

A limited number of acceptance tests are available in theproxmoxtf/test directory, mostly for "new" functionality implemented using the Terraform Provider Framework.These tests are not run by default, as they require a Proxmox VE environment to be available.They can be run usingmake testacc. The Proxmox connection can be configured using environment variables; see the provider documentation for details.

There are a number of TF examples in theexample directory, which can be used to deploy a Container, VM, or other Proxmox resources in your test Proxmox environment.

The following assumptions are made about the test environment:

• It has one node namedpve
• The node has local storages namedlocal andlocal-lvm
• The "Snippets" and "Import" content types are enabled in thelocal storage
• Default Linux Bridge "vmbr0" is VLAN aware (datacenter -> pve -> network -> edit & apply)

Createexample/terraform.tfvars with the following variables:

virtual_environment_endpoint                 ="https://pve.example.com:8006/"virtual_environment_ssh_username             ="terraform"virtual_environment_api_token                ="root@pam!terraform=00000000-0000-0000-0000-000000000000"

Then runmake example to deploy the example resources.

If you don't have a free Proxmox cluster to play with, there is a dedicatedhow-to tutorial on how to set up Proxmox inside a VM and runmake example on it.

The provider is using theTerraform SDKv2, which is considered legacy and is in maintenance mode.Work has started to migrate the provider to the newTerraform Plugin Framework, with the aim of releasing it as a new major version1.0.

Proxmox VE 9.0 has a new API for managing HA resources, which is not yet supported by the provider, see#2097 for more details.

apt_* resources / datasources do not support the new deb822 style format.

If a VM or container resource is created with the provider but managed by an HA cluster, it might be migrated to a different node without the provider being aware of the change.This causes a "configuration drift" and the provider will report an error when managing the resource.You would need to manually reconcile the resource state stored in the backend to match the actual state of the resource, or remove the resource from the provider management.

Debian 12 and Ubuntu VMs throw kernel panic when resizing a cloud image boot disk, as they require a serial device configured.Add the following block to your VM config:

serial_device {device="socket"  }

For more context, see issues #1639 and #1770.

Proxmox VE does not currently support VMware disk images directly.However, you can still use them as disk images by using this workaround:

resource"proxmox_virtual_environment_file""vmdk_disk_image" {content_type="iso"datastore_id="datastore-id"node_name="node-name"source_file {# We must override the file extension to bypass the validation code# in the Proxmox VE API.file_name="vmdk-file-name.img"path="path-to-vmdk-file"  }}resource"proxmox_virtual_environment_vm""example" {//...disk {datastore_id="datastore-id"# We must tell the provider that the file format is vmdk instead of qcow2.file_format="vmdk"file_id="${proxmox_virtual_environment_file.vmdk_disk_image.id}"  }//...}

Due to limitations in the Proxmox VE API, certain files (snippets, backups) need to be uploaded using SFTP.This requires the use of a PAM account (standard Linux account).

Due to limitations in the Proxmox VE API, cluster hardware mappings must be created using theroot PAM account (standard Linux account) because ofIOMMU interactions.Hardware mappings allow the use ofPCI "passthrough" andmap physical USB ports.

Creating multiple VMs or containers simultaneously can cause lock errors due to I/O bottlenecks in Proxmox VE (PVE).Using sequential creation or settingparallelism=1 can help mitigate this issue.

Additional information and sample error messages can be found in issues#1929 &#995.

An OpenTofu feature request to help with configuring provider parallelization is tracked at#2466. Consider adding a 👍 to help with prioritization, as suggested by the team in thiscomment.

SeeCONTRIBUTORS.md for a list of contributors to this project.

❤️ This project is sponsored by:

• Elias Alvord
• laktosterror
• Greg Brant
• Serge
• Daniel Brennand
• Brian King
• Radosław Szamszur
• Marshall Ford
• Simon Caron

Thanks again for your continuous support, it is much appreciated! 🙏

This project has been developed withGoLand IDE under theJetBrains Open Source license, generously provided by JetBrains s.r.o.