Skip to content
agovena.
agovena.
Get started
Community

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

  1. Enable the Provisioning Module, then install and enable Virtualizor in Admin > Extensions.
  2. Save api_url as scheme://host:port without a path, for example https://vz.example.com:4085.
  3. Save the Admin API key in api_token and the Admin API password in api_secret. Both are encrypted at rest.
  4. Keep verify_tls enabled.
  5. Run Test connection. It reads the plan list.
  6. 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 error list or refused credentials prove that nothing was created; the claim becomes failed and a retry creates again. A timeout, HTTP error or unexpected body leaves the claim unknown. 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 a space array are removed. Agovena sends no space array, 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.

View the package entry

Sources

Search documentation

Search guides, commands and API endpoints

What are you looking for?

Documentation