Provider guides
Proxmox VE: configuration and operations
Provision Proxmox VE QEMU virtual machines by cloning a template, with lifecycle actions, plan changes, status sync and customer power actions.
On this page
Status and workflow
The Proxmox VE extension provisions QEMU virtual machines with a full clone of a template VMID on the configured node and storage, then applies the purchased CPU, memory, disk and network settings. It supports suspension, unsuspension, termination, plan changes, status synchronization, a customer panel and customer start, stop and reboot. Long-running clone, resize and delete operations are followed through Proxmox task polling.
Production-ready for the documented scope. Every operation under Supported operations is implemented against the Proxmox VE API and verified with automated tests that replace the provider with faked HTTP responses, without network calls. Live acceptance on your own Proxmox VE account remains an operator responsibility: clone, suspend, unsuspend, resize and delete one VM from a disposable template on your own cluster before you sell it. Operations under Not supported are not advertised.
Requirements
- Agovena Core
^0.0.1. - The Provisioning Module, enabled before this extension.
- A Proxmox VE node with a QEMU template VM and storage for the clones.
- A Proxmox API token for a user with rights on that node, storage and template.
Set up the package
- Enable the Provisioning Module, then install and enable Proxmox in Admin > Extensions.
- Create an API token in Proxmox VE.
- Save
api_urlas the root URL, for examplehttps://pve.example.com:8006. The extension appends/api2/json. Paths, query strings, fragments and credentials in the URL are refused. - Save
token_userincluding its realm,token_idandtoken_secret. They form thePVEAPITokenauthorization header. The secret is encrypted at rest. - Save the
nodeandstoragefor new VMs and keepverify_tlsenabled. - Run Test connection.
- On each provisionable product, set
template_vmidand reviewcores(default 1),memory(default 1024),disk(default 20),sockets(default 1),cpu_type(defaulthost),bridge(defaultvmbr0) andautostart(default on). These defaults are a starting point, not proof that your template, storage or bridge can satisfy them.
Supported operations
- Create with a full clone of
template_vmid, followed by the configured CPU, memory, disk and network settings. The VM description carries an ownership marker for the service instance and the mapping is stored inproxmox_vms. - Capacity: node and storage capacity are reported to the Provisioning Module so stock checks can refuse orders that do not fit.
- Suspend stops the VM, sets
onbootto 0 and verifies both. Unsuspend setsonbootto 1, starts the VM and verifies that it runs. - Terminate deletes only a VM that carries this instance's ownership marker and verifies that it is gone.
- Change plan applies the new product settings. Disks are grown, never shrunk, because Proxmox VE does not shrink disks.
- Status sync:
runningandstoppedmap to active or suspended, every other state goes to manual review. - Customer actions start, stop and reboot. Stop and reboot are marked as dangerous actions.
Not supported
- LXC containers and Proxmox resource types other than QEMU virtual machines.
- IP pools, operating system catalogs, a backup interface and bandwidth metering.
- Shrinking disks on a plan downgrade.
Failure handling and ownership
- Suspend, unsuspend and terminate first check that the VM carries the ownership marker of this service instance. A VM without that marker is never changed or deleted.
- A clone can succeed while the mapping write fails, for example after a timeout. Terminate then finds the VM by its deterministic name and deletes it only when it carries the marker.
- Clone, resize, start, stop and delete wait for the Proxmox task to finish. An HTTP response alone is not proof that the VM is ready.
- Malformed responses and insufficient capacity fail instead of implying availability. After an interrupted operation, compare the mapping, remote configuration and task status before you try another clone.
- Redirects are never followed and the token is sent only in the authorization header, never in the URL.
Configuration contract
| Field | Type | Required | Secret | Default |
|---|---|---|---|---|
api_url |
string |
Yes | No | Empty |
token_user |
string |
Yes | No | Empty |
token_id |
string |
Yes | No | Empty |
token_secret |
string |
Yes | Yes | Empty |
node |
string |
Yes | No | Empty |
storage |
string |
Yes | No | Empty |
verify_tls |
boolean |
No | No | true |
timeout |
string |
No | No | "30" |
timeout defaults to 30 seconds per request. Task polling for clone and delete runs separately from that request timeout. Store secret values only in the protected extension settings, never in product descriptions, URLs, screenshots or shared examples.