Provider guides
Convoy: configuration and operations
Create, suspend, unsuspend, terminate and resize Convoy v4.6.1 virtual servers, with status sync and a customer panel.
On this page
Status and workflow
The Convoy extension provisions virtual servers through the Convoy application API. It is built and verified against Convoy v4.6.1; the main branch (4.7 release candidate) uses a different route layout and is not supported until every call is verified again. For each Agovena service it creates or reuses the Convoy user Agovena created for that customer and creates a server from a template. It supports suspension, unsuspension, termination, resource limit changes, status synchronization, a customer panel and a health check.
Production-ready for the documented scope. Every operation under Supported operations is implemented against the Convoy v4.6.1 application API source and verified with automated tests that replace the provider with faked HTTP responses, without network calls. Live acceptance on your own Convoy account remains an operator responsibility: create, suspend, unsuspend, resize and terminate one disposable server on your own Convoy v4.6.1 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 Convoy
v4.6.1panel reachable over HTTPS and an application API token of a Convoy administrator. - A node ID and template UUID for each product. Convoy has no packages: the product limits are the plan.
Set up the package
- Enable the Provisioning Module, then install and enable Convoy in Admin > Extensions.
- Save
api_urlasscheme://host[:port]without a path, for examplehttps://convoy.example.com, and the administrator application API token inapi_token. The token is encrypted at rest. - Keep
verify_tlsenabled. - Run Test connection. It calls the read-only
GET /servers?per_page=1. - On each provisionable product, set Node ID, Template UUID, CPU cores, Memory (MiB), Disk (MiB), Bandwidth (GiB) (empty is unlimited), Snapshot limit and Backup limit.
Supported operations
Calls go to https://host:port/api/application/... with a bearer token. Servers are addressed by their full UUID, and memory, disk and bandwidth are sent and compared in bytes.
| Operation | Method and path |
|---|---|
| Health check | GET /servers?per_page=1 |
| Create user | POST /users with a generated password and root_admin=false |
| Create server | POST /servers with node, template, limits and start_on_completion=true |
| Status sync, plan change read | GET /servers/{uuid} |
| Suspend | POST /servers/{uuid}/settings/suspend |
| Unsuspend | POST /servers/{uuid}/settings/unsuspend |
| Terminate | DELETE /servers/{uuid}; 404 for the recorded UUID means already gone |
| Resource limit change | PATCH /servers/{uuid}/settings/build |
A limit change re-sends the current IPv4 and IPv6 address IDs, because Convoy detaches every address missing from the request. Convoy swallows hypervisor sync failures during this call, so the stored plan changes only after a fresh read confirms the new limits and the same addresses.
Status mapping: null is active, suspended is suspended, installing, restoring_backup and restoring_snapshot report provisioning, install_failed is refused as a failed build, and deleting, deletion_failed or any unknown value is refused for manual review.
Not supported
- Convoy versions other than
v4.6.1, including the 4.7mainbranch. - Power actions, customer single sign-on and capacity checks.
- Deleting Convoy users. Terminate removes only the server.
- Moving a server to another node or reinstalling a template on a plan change.
Failure handling and ownership
- Response shapes are validated strictly; anything else fails closed. Calls never follow redirects, verify TLS, pin DNS through the shared provisioning HTTP client and are refused in the
demoenvironment. Production refuses plain HTTP and unverified TLS. - Ownership is proven only by a row in
convoy_accounts, inserted under a per-service lock before any create call. HTTP calls run outside database transactions and every state change is a conditional update onrevision. - A Convoy 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
422and fails the claim. - A
422from user or server create, refused credentials or a failure before sending prove that nothing was created. The claim becomesfailedand a retry creates again, keeping a recorded user. Timeouts, other errors and unexpected bodies leave the claimunknown. Convoy returns no identifier Agovena could have chosen, so the create is never retried and the service goes to manual review. - 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 generated user password and server password are sent once and never stored, logged or returned. Customers set their own password through the Convoy password reset.
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" |
api_token must be an application API token of a Convoy administrator. timeout defaults to 20 seconds. Store secret values only in the protected extension settings, never in product descriptions, URLs, screenshots or shared examples.