terraform-provider-proxmox

Terraform / OpenTofu Provider for Proxmox VE

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

Maintained by BPG Labs.

Disclaimer

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

The project is not affiliated with Proxmox 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.

Quick Start

terraform {
  required_providers {
    proxmox = {
      source = "bpg/proxmox"
    }
  }
}

provider "proxmox" {
  endpoint  = "https://pve.example.com:8006/"
  api_token = "terraform@pve!provider=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Most resources work entirely through the Proxmox VE API. SSH access to the nodes is only needed for a few operations, such as uploading snippets. See the provider documentation at bpg.sh/docs for authentication options, SSH configuration, the full list of resources and data sources, and the known issues.

Releases are published to the Terraform Registry and the OpenTofu Registry. Binaries for manual installation are on the Releases page, and their provenance can be verified with gh, see attestations.

Compatibility

This provider targets Proxmox VE 9.x and is acceptance-tested against the current 9.x release.

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.

Terraform and OpenTofu version requirements are listed in the provider documentation.

Security

• Report vulnerabilities privately as described in SECURITY.md. Do not open public issues for them.
• Published advisories are listed on the security advisories page.
• Nearly all operations use the Proxmox VE API. Use an API token with only the privileges your resources need.
• The few operations that require SSH run commands on the node through sudo. Use the sudoers configuration from the SSH User section of the documentation as written. Granting the SSH user unrestricted sudo access to binaries such as qm or pvesm is equivalent to giving it root on the host.

Building and Testing the Provider

Building requires Go 1.26. Docker is optional, for running the dev tools.

make build

Unit tests cover the API client, model conversion and schema logic, and run with:

make test

Most of the test coverage is acceptance tests, which exercise the provider end-to-end against a real Proxmox VE instance. They live next to the resource or data source they cover (and in fwprovider/test for cross-resource scenarios), are grouped into light/medium/heavy tiers, and are run with ./testacc (requires testacc.env in the project root, see CONTRIBUTING.md). They are not run in CI by default, as they require a Proxmox VE environment; maintainers run them against a lab cluster before merging changes, and new or changed functionality must come with acceptance tests.

Example Resources

The example directory contains sample configurations, mostly for the legacy SDKv2 resources; Framework resources are covered by their acceptance tests instead. make example builds the provider, applies the samples against a test Proxmox VE environment, and destroys them again, so it needs a dedicated environment and an example/terraform.tfvars. See Setting up Proxmox in a VM for development for the prerequisites and configuration.

Future Work

The provider was originally built on the Terraform SDKv2, which is considered legacy and is in maintenance mode. New resources and data sources are implemented with the Terraform Plugin Framework, and both are served from a single binary. The core resources, including proxmox_virtual_environment_vm, proxmox_virtual_environment_container, proxmox_virtual_environment_file and the firewall and access-control resources, are still on SDKv2 and continue to receive fixes and enhancements there. Migrating them to the Plugin Framework, starting with the VM resource (#1231), is a prerequisite for the 1.0 release.

Contributors

See CONTRIBUTORS.md for a list of contributors to this project.

History

The provider was forked in 2021 from danitso/terraform-provider-proxmox after upstream maintenance stopped, and has been developed independently since.

Repository Metrics

Sponsorship

❤️ This project is sponsored by:

• Elias Alvord
• laktosterror
• Greg Brant
• Serge
• Daniel Brennand
• Brian King
• Marshall Ford
• Simon Caron

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

Acknowledgements

This project has been developed with GoLand IDE under the JetBrains Open Source license, generously provided by JetBrains s.r.o.