Provider guides
Virtualizor: configuration and operations
Create, suspend, unsuspend, terminate and change Virtualizor VPSs through the Virtualizor Admin API, with status sync.
On this page
Status and workflow
The Virtualizor extension provisions VPSs through the Virtualizor Admin API. For each Agovena service it creates a VPS and its Virtualizor user, or attaches the VPS to the user an earlier Agovena create recorded for the same customer. It supports suspension, unsuspension, termination, plan changes, plan listing, status synchronization and a customer panel.
Production-ready for the documented scope. Every operation under Supported operations is implemented against the Virtualizor Admin API documentation and verified with automated tests that replace the provider with faked HTTP responses, without network calls. Live acceptance on your own Virtualizor account remains an operator responsibility: create, suspend, unsuspend, change and terminate one disposable VPS on your own panel before you sell it, and test plan changes on multi-disk VPSs separately. Operations under Not supported are not advertised.
Requirements
- Agovena Core
^0.0.1. - The Provisioning Module, enabled before this extension.
- A Virtualizor master reachable over HTTPS, with the Admin API key and password from Configuration > Server Info.
- Enabled Virtualizor plans, operating system template IDs and server group IDs for your products.
Set up the package
- Enable the Provisioning Module, then install and enable Virtualizor in Admin > Extensions.
- Save
api_urlasscheme://host:portwithout a path, for examplehttps://vz.example.com:4085. - Save the Admin API key in
api_tokenand the Admin API password inapi_secret. Both are encrypted at rest. - Keep
verify_tlsenabled. - Run Test connection. It reads the plan list.
- On each provisionable product, set Plan ID (an enabled plan), Operating system template ID and Server group ID, where 0 is the default group.
Supported operations
Every call goes to https://host:port/index.php?act=...&api=json with the documented adminapikey and adminapipass query parameters.
| Operation | Request |
|---|---|
| Health check, plan check, list plans | POST act=plans |
| Foreign user check on create | POST act=users by email |
| Create VPS and user | POST act=addvs |
| Status sync, ownership check | GET act=vs&vpsid={id} |
| Suspend | GET act=vs&suspend={id} |
| Unsuspend | GET act=vs&unsuspend={id} |
| Terminate | GET act=vs&delete={id} after the ownership check |
| Plan change | POST act=managevps with plid, apply_plan=1 and editvps=1 after the plan and ownership checks |
Virtualizor answers failures with HTTP 200, so every response must be a JSON object, any non-empty error fails the call and the documented success field is checked. A plan change is accepted only when a fresh VPS read reports the new plid.
Not supported
- Power actions, customer single sign-on and capacity checks.
- Deleting Virtualizor users. Terminate removes only the VPS.
- Automatic recovery of an interrupted create. It always needs manual review.
- Plans beyond the first page of 1000 plans. Such a plan is reported as unavailable.
Failure handling and ownership
- Because the credentials are query parameters, request URLs are never put in exceptions, messages or logs. Transport errors surface only as translation keys.
- Ownership is proven only by a row in
virtualizor_accounts, inserted under a per-service lock before any create call. The VPS ID replaces the placeholder in the same conditional update that marks the claim active. - A later service of the same customer on the same panel passes the user ID that an earlier Agovena create recorded, and the returned user ID must match. Without a recorded user, any existing Virtualizor user with the same email blocks the create, so a user found only by lookup is never adopted.
- A non-empty
errorlist or refused credentials prove that nothing was created; the claim becomesfailedand a retry creates again. A timeout, HTTP error or unexpected body leaves the claimunknown. Because no VPS ID was recorded, it is never retried and the service goes to manual review. - Terminate, plan change and status sync first read the VPS by its recorded ID and require the recorded user. A missing VPS goes to manual review. Terminate keeps the row as
terminated. - Plan change applies the plan through
apply_plan. The Virtualizor documentation warns that disks missing from aspacearray are removed. Agovena sends nospacearray, so test plan changes on multi-disk VPSs before offering them. - The generated root and user passwords are sent once and never stored. Virtualizor 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 |
api_secret |
string |
Yes | Yes | Empty |
verify_tls |
boolean |
No | No | true |
timeout |
string |
No | No | "20" |
api_token holds the Admin API key and api_secret the Admin API password. 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.