Skip to content
agovena.
agovena.
Get started
Community

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.1 panel 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

  1. Enable the Provisioning Module, then install and enable Convoy in Admin > Extensions.
  2. Save api_url as scheme://host[:port] without a path, for example https://convoy.example.com, and the administrator application API token in api_token. The token is encrypted at rest.
  3. Keep verify_tls enabled.
  4. Run Test connection. It calls the read-only GET /servers?per_page=1.
  5. 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.7 main branch.
  • 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 demo environment. 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 on revision.
  • 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 422 and fails the claim.
  • A 422 from user or server create, refused credentials or a failure before sending prove that nothing was created. The claim becomes failed and a retry creates again, keeping a recorded user. Timeouts, other errors and unexpected bodies leave the claim unknown. 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_mapping without a claim row is refused without network. Terminate keeps the row as terminated.
  • 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.

View the package entry

Sources

Search documentation

Search guides, commands and API endpoints

What are you looking for?

Documentation