Telmate terraform-provider-proxmox: provisioning QEMU VMs and LXC containers with Terraform

The gap Telmate/terraform-provider-proxmox fills in a Proxmox homelab or cluster

Proxmox VE has its own web UI and its own API, and neither one is Terraform. If you run a small cluster, the usual pattern is to click through the UI once, then forget what settings you chose six months later. The Telmate provider closes that gap: it is a Terraform provider plugin for the Proxmox virtualization platform that exposes Terraform resources to provision QEMU VMs and LXC Containers, according to the README. It is written in Go and licensed under MIT.

The audience is narrow and specific. You need a working Proxmox installation, an API token or credentials the provider can use, and a reason to want guests described in HCL rather than in the Proxmox UI. That reason is usually repetition: the same VM shape across several nodes, or the same container image with different hostnames. If you provision one VM a year, the provider adds a state file and a plugin download for very little return.

The repository is not archived, and the last push was on 2026-09-14. The most recent published releases are v3.0.2-rc10 (2026-08-30), v3.0.2-rc09 (2026-08-14) and v3.0.2-rc08 (2026-07-05). All three are release candidates, which is worth knowing before you point a production pipeline at the newest tag.

How the provider talks to Proxmox VE

The architecture is the standard Terraform plugin split. Terraform core runs as one process; the provider is a separate binary that Terraform launches and speaks to over the plugin protocol. The provider binary is built from main.go at the repository root, and the schema and resource implementations live under the proxmox/ directory. The dependency list in go.mod pins the moving parts: github.com/hashicorp/terraform-plugin-sdk/v2 v2.40.1 for the plugin framework, and github.com/Telmate/proxmox-api-go as the client that actually calls the Proxmox API. The module path is github.com/Telmate/terraform-provider-proxmox/v2 and the module declares go 1.26.2.

That layering matters when something breaks. A schema problem surfaces in Terraform's plan output; an API problem surfaces as an error from proxmox-api-go, often as a task that failed on the Proxmox side. The README's Known Limitations section is essentially a list of places where the two layers disagree. The most concrete example: the proxmox_vm_qemu disk size attribute does not match what is displayed in the Proxmox UI. Another: updates to proxmox_vm_qemu resources almost always result as a failed task within the Proxmox UI, which the README calls harmless because the desired configuration changes do get applied. Treat that as a description of the current behaviour, not as a promise that it will stay that way.

The provider also supports network boot. The README states that in PXE mode a valid NIC must be defined for the VM and the boot order must specify network first. It does not describe what happens if you get that wrong.

Installing the plugin and provisioning a first guest

The README points to docs/guides/installation.md for installation and to docs/index.md for the provider options and for guides on combining options and starting specific VMs. Those two files are where the actual install steps live; the README itself only links to them. Follow them rather than improvising a plugin path, because the provider is distributed as a plugin binary and Terraform needs to find it in the right place for your Terraform version.

If you build from source instead, the repository has a Makefile and a .goreleaser.yml. The Makefile derives a version from git describe --match "v*" --always --tags, splits the tag into major, minor and micro parts, and computes next-version tags from the number of commits since the last tag. It also branches on uname -s and uname -m to pick a kernel and architecture, mapping Linux to linux, Darwin to darwin, and x86_64 to amd64. A build therefore depends on git history being present, not just the working tree.

For debugging, the README notes that debugging is available through Terraform Plugin SDK versions 2.0.0 and that the plugin can be started with the --debug flag. The example it gives uses delve:

dlv exec --headless ./terraform-provider-my-provider -- --debug

Once the plugin is installed and the provider block is configured with your Proxmox endpoint and credentials, a first resource is a proxmox_vm_qemu or a proxmox_lxc block. For proxmox_lxc, define rootfs. The README is blunt about the alternative: the provider will crash unless rootfs is defined. That is not a graceful validation error you can read and fix from the plan output, so make it the first attribute you write.

Known limitations that show up as failed tasks and crashes

The README lists four limitations, and they are not equally serious. The cosmetic one is the proxmox_vm_qemu disk size attribute disagreeing with the Proxmox UI. Annoying when you are reconciling state by eye, harmless otherwise.

The operational one is that updates to proxmox_vm_qemu almost always produce a failed task in the Proxmox UI. The README says the changes do get applied. If you have alerting wired to Proxmox task failures, this provider will generate noise on every change, and you will have to decide whether to filter it or to stop alerting on that task class. That is a real integration cost, and the documentation does not offer a way to suppress it.

The hard failure is proxmox_lxc without rootfs: the provider crashes. A crash in a plugin process is worse than a validation error because it can interrupt an apply mid-run, and the README does not document rollback behaviour for that case.

PXE is the fourth. The README requires a valid NIC and a boot order that specifies network first. It does not say what error you get when either is missing, so budget time for reading Proxmox-side logs if a network boot VM does not start.

None of these are reasons to avoid the provider outright. They are reasons to read the Known Limitations section before you design a pipeline around it, and to keep the Proxmox UI open the first few times you apply.

Telmate compared with the bpg Proxmox provider

The search data around this project is dominated by comparisons. People search for the bpg Proxmox provider, for terraform provider proxmox bpg, and for the best Proxmox Terraform provider, which tells you the decision is usually framed as Telmate versus bpg rather than Telmate versus nothing.

Only one side of that comparison is documented here. What can be said from the repository itself: Telmate's provider is written in Go, is MIT licensed, declares its module as github.com/Telmate/terraform-provider-proxmox/v2, and builds on terraform-plugin-sdk/v2 with proxmox-api-go as the API client. Its README publishes a Known Limitations list, which is itself useful information: the maintainers are telling you where the edges are rather than leaving you to find them. The bpg provider is not described in the Telmate repository at all, so any claim about how it differs in mechanism, resource coverage or release cadence would be invented.

The practical approach is to treat the choice as a testable question rather than a preference. Both providers target the same Proxmox API. Pick the one whose documented resource attributes cover the guest settings you actually change, and check whether its release cadence matches your tolerance for release candidates. On that last point, Telmate's three most recent releases are all v3.0.2 release candidates, which is a fact you can weigh without knowing anything about the alternative.

Maintenance, upgrade cost and the MIT licence

The repository is not archived and the last push was on 2026-09-14, so there is recent activity on master. That does not mean the provider is stable in the sense of a long-lived release branch: the newest tags are v3.0.2-rc10, v3.0.2-rc09 and v3.0.2-rc08, spaced roughly six weeks and then two weeks apart. If you pin to a release candidate you should expect to move when the next one lands, and you should expect the module path to keep the /v2 suffix until a major bump.

Upgrade cost concentrates in two places. The first is the provider schema, because a changed attribute in proxmox_vm_qemu or proxmox_lxc can force a resource replacement rather than an in-place update. The second is the Proxmox API client, proxmox-api-go, which go.mod pins to a pseudo-version rather than a tagged release. That pin is updated in the provider repository, not by you, so an upgrade can change API behaviour without any visible change in your HCL.

The licence is MIT. MIT is permissive: it allows use, modification and redistribution with the copyright notice and permission notice retained. This is not legal advice, and the LICENSE file at the repository root is the authoritative text. If you vendor the provider into a commercial product, read that file rather than this paragraph. Note also that the provider depends on HashiCorp's terraform-plugin-sdk, which carries its own licence terms, and on other third-party modules listed in go.mod.

Editorial conclusion

Adopt it if your Proxmox guests are already managed by hand and you want them in Terraform state, and you accept the documented rough edges: disk size that disagrees with the Proxmox UI, failed tasks on update, and a crash on proxmox_lxc without rootfs. Do not adopt it if you need a fully silent apply or you are unwilling to run release candidates, since the newest published releases are v3.0.2-rc10, v3.0.2-rc09 and v3.0.2-rc08. Verify first that your Proxmox version matches what the repository's docs/index.md supports, and read docs/guides/installation.md before writing any resource block.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. Telmate/terraform-provider-proxmox on GitHub