Provider guides
VirtFusion: configuration and operations
Create, build, suspend, unsuspend, terminate and change VirtFusion virtual servers through the VirtFusion API v1, with status sync.
On this page
Status and workflow
The VirtFusion extension provisions virtual servers through the VirtFusion API v1. For each Agovena service it creates or reuses the VirtFusion user Agovena created for that customer, creates a server from the product package and builds it with the product operating system template. It supports suspension, unsuspension, termination, plan changes, package checks, status synchronization and a customer panel.
Production-ready for the documented scope. Every operation under Supported operations is implemented against the VirtFusion API v1 documentation and verified with automated tests that replace the provider with faked HTTP responses, without network calls. Live acceptance on your own VirtFusion account remains an operator responsibility: create, build, suspend, unsuspend, change and terminate one disposable server on your own panel 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 VirtFusion panel reachable over HTTPS and a VirtFusion API token.
- Enabled VirtFusion packages, a hypervisor group ID and an operating system template ID for each product.
Set up the package
- Enable the Provisioning Module, then install and enable VirtFusion in Admin > Extensions.
- Save
api_urlasscheme://host[:port]without a path, for examplehttps://cp.example.com, and the API token inapi_token. The token is encrypted at rest. - Keep
verify_tlsenabled. - Run Test connection. It calls the read-only
GET /connect. - On each provisionable product, set Package ID (an enabled VirtFusion package), Hypervisor group ID and Operating system template ID.
Supported operations
Calls go to https://host:port/api/v1/... with a bearer token.
| Operation | Method and path |
|---|---|
| Health check | GET /connect |
| Package check | GET /packages |
| Create user | POST /users with sendMail=true |
| Reconcile an interrupted user create | GET /users/{relStr}/byExtRelation |
| Create server | POST /servers with packageId, userId, hypervisorId |
| Build server | POST /servers/{id}/build with operatingSystemId and email=true |
| Status sync, reconcile a build | GET /servers/{id} |
| Suspend | POST /servers/{id}/suspend |
| Unsuspend | POST /servers/{id}/unsuspend |
| Terminate | DELETE /servers/{id} without delay; 404 means already gone |
| Plan change | PUT /servers/{id}/package/{packageId} |
A plan change first confirms that the target package exists and is enabled, then asks every documented resource to follow the new package. Only a 200 with an info list is accepted. VirtFusion never shrinks a primary disk and reports skipped resources in info.
Not supported
- Power actions, customer single sign-on and capacity checks.
- Deleting VirtFusion users. Terminate removes only the server.
Failure handling and ownership
- Ownership is proven only by a row in
virtfusion_accounts, inserted with a random relation string before any create call. VirtFusion's integerextRelationIdcannot be namespaced, so the documented relation string carries the link. - A VirtFusion user is created per customer and endpoint. A later service of the same customer on the same panel reuses the user ID that an earlier Agovena create recorded. A user found only by email or lookup is never adopted; a duplicate email is a documented
409and fails the claim. 409and422from user or server create and refused credentials prove that nothing was created. The claim becomesfailedand a retry creates again. Timeouts, other errors and unexpected bodies leave the claimunknownand the service goes to manual review.- Reconciliation reads only recorded identifiers. A server whose owner matches the recorded user but is not built yet is built again; VirtFusion refuses that with
423while a build runs. A server create without a returned ID is never retried. - Lifecycle calls require the claim state and current endpoint to match. A re-pointed panel or a hand-written
provider_mappingwithout a claim row is refused without network. Terminate keeps the row asterminated. - The user password from the create response is never stored. VirtFusion emails the access details to the customer.
Configuration contract
| Field | Type | Required | Secret | Default |
|---|---|---|---|---|
api_url |
string |
Yes | No | Empty |
api_token |
string |
Yes | Yes | Empty |
verify_tls |
boolean |
No | No | true |
timeout |
string |
No | No | "20" |
Calls never follow redirects, verify TLS, pin DNS through the shared provisioning HTTP client and are refused in the demo environment. Production refuses plain HTTP and unverified TLS. Store secret values only in the protected extension settings, never in product descriptions, URLs, screenshots or shared examples.