Skip to content
agovena.
agovena.
Get started
Community

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

  1. Enable the Provisioning Module, then install and enable Proxmox in Admin > Extensions.
  2. Create an API token in Proxmox VE.
  3. Save api_url as the root URL, for example https://pve.example.com:8006. The extension appends /api2/json. Paths, query strings, fragments and credentials in the URL are refused.
  4. Save token_user including its realm, token_id and token_secret. They form the PVEAPIToken authorization header. The secret is encrypted at rest.
  5. Save the node and storage for new VMs and keep verify_tls enabled.
  6. Run Test connection.
  7. On each provisionable product, set template_vmid and review cores (default 1), memory (default 1024), disk (default 20), sockets (default 1), cpu_type (default host), bridge (default vmbr0) and autostart (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 in proxmox_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 onboot to 0 and verifies both. Unsuspend sets onboot to 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: running and stopped map 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.

View the package entry

Sources

Search documentation

Search guides, commands and API endpoints

What are you looking for?

Documentation