Ga naar de inhoud
agovena.
agovena.
Aan de slag
Community

Providerhandleidingen

Convoy: instellen en beheren

Maak, schort op, hervat, beëindig en wijzig de resources van virtuele servers op Convoy v4.6.1, met statussync en een klantpaneel.

Op deze pagina

Status en werkwijze

De Convoy-extension levert virtuele servers via de Convoy application API. De extension is gebouwd en geverifieerd tegen Convoy v4.6.1; de main-branch (release candidate 4.7) gebruikt een andere route-indeling en wordt pas ondersteund als elke call opnieuw is geverifieerd. Per Agovena-dienst maakt de extension de Convoy-gebruiker voor die klant aan of hergebruikt de gebruiker die Agovena eerder aanmaakte, en maakt een server vanuit een template. De extension ondersteunt opschorten, hervatten, beëindigen, wijzigen van resourcelimieten, statussynchronisatie, een klantpaneel en een health check.

Production-ready voor de gedocumenteerde scope. Elke bewerking onder Ondersteunde bewerkingen is gebouwd op de bron van de Convoy v4.6.1 application API en geverifieerd met geautomatiseerde tests die de provider vervangen door gesimuleerde HTTP-antwoorden, zonder netwerkcalls. Live acceptatie op je eigen Convoy-account blijft de verantwoordelijkheid van de beheerder: maak, schort op, hervat, wijzig en beëindig één wegwerpserver op je eigen Convoy v4.6.1-paneel voordat je het product verkoopt. Bewerkingen onder Niet ondersteund worden niet aangeboden.

Vereisten

  • Agovena Core ^0.0.1.
  • De Provisioning Module, geactiveerd vóór deze extension.
  • Een Convoy v4.6.1-paneel dat via HTTPS bereikbaar is en een application API-token van een Convoy-beheerder.
  • Een node-ID en template-UUID per product. Convoy heeft geen packages: de productlimieten zijn het plan.

Het pakket instellen

  1. Activeer de Provisioning Module en installeer en activeer daarna Convoy in Admin > Extensies.
  2. Sla api_url op als scheme://host[:port] zonder pad, bijvoorbeeld https://convoy.example.com, en de application API-token van de beheerder in api_token. De token wordt versleuteld opgeslagen.
  3. Laat verify_tls aan.
  4. Voer Test connection uit. Die roept de alleen-lezen GET /servers?per_page=1 aan.
  5. Stel op elk provisionable product Node ID, Template UUID, CPU cores, Memory (MiB), Disk (MiB), Bandwidth (GiB) (leeg is onbeperkt), Snapshot limit en Backup limit in.

Ondersteunde bewerkingen

Calls gaan naar https://host:port/api/application/... met een bearer token. Servers worden aangesproken met hun volledige UUID, en geheugen, schijf en bandbreedte worden in bytes verstuurd en vergeleken.

Bewerking Methode en pad
Health check GET /servers?per_page=1
Gebruiker aanmaken POST /users met een gegenereerd wachtwoord en root_admin=false
Server aanmaken POST /servers met node, template, limieten en start_on_completion=true
Statussync, uitlezen bij planwijziging GET /servers/{uuid}
Opschorten POST /servers/{uuid}/settings/suspend
Hervatten POST /servers/{uuid}/settings/unsuspend
Beëindigen DELETE /servers/{uuid}; 404 voor de vastgelegde UUID betekent al verwijderd
Resourcelimieten wijzigen PATCH /servers/{uuid}/settings/build

Een limietwijziging stuurt de huidige IPv4- en IPv6-adres-ID's opnieuw mee, omdat Convoy elk adres loskoppelt dat in het verzoek ontbreekt. Convoy verzwijgt synchronisatiefouten met de hypervisor tijdens deze call, dus het opgeslagen plan verandert pas als een nieuwe uitlezing de nieuwe limieten en dezelfde adressen bevestigt.

Statusvertaling: null is actief, suspended is opgeschort, installing, restoring_backup en restoring_snapshot gelden als provisioning, install_failed wordt geweigerd als mislukte build, en deleting, deletion_failed of elke onbekende waarde wordt geweigerd voor handmatige controle.

Niet ondersteund

  • Andere Convoy-versies dan v4.6.1, ook de main-branch van 4.7.
  • Poweracties, single sign-on voor klanten en capaciteitscontroles.
  • Convoy-gebruikers verwijderen. Beëindigen verwijdert alleen de server.
  • Een server naar een andere node verplaatsen of een template opnieuw installeren bij een planwijziging.

Foutafhandeling en eigendom

  • Antwoordstructuren worden strikt gevalideerd; al het andere faalt veilig. Calls volgen nooit redirects, controleren TLS, pinnen DNS via de gedeelde provisioning-HTTP-client en worden geweigerd in de demo-omgeving. Productie weigert gewone HTTP en ongecontroleerde TLS.
  • Eigendom wordt alleen bewezen door een rij in convoy_accounts, ingevoegd onder een lock per dienst vóór elke aanmaakcall. HTTP-calls lopen buiten databasetransacties en elke statuswijziging is een voorwaardelijke update op revision.
  • Per klant en endpoint wordt één Convoy-gebruiker aangemaakt. Een latere dienst van dezelfde klant op hetzelfde paneel hergebruikt het gebruikers-ID dat een eerdere aanmaak door Agovena vastlegde. Een gebruiker die alleen via e-mail of een zoekactie wordt gevonden, wordt nooit overgenomen; een dubbel e-mailadres geeft een 422 en laat de claim falen.
  • Een 422 bij het aanmaken van gebruiker of server, geweigerde inloggegevens of een fout vóór verzending bewijzen dat er niets is aangemaakt. De claim wordt failed en een nieuwe poging maakt opnieuw aan, met behoud van een vastgelegde gebruiker. Timeouts, andere fouten en onverwachte bodies laten de claim op unknown staan. Convoy geeft geen ID terug dat Agovena zelf had kunnen kiezen, dus de aanmaak wordt nooit herhaald en de dienst gaat naar handmatige controle.
  • Levenscycluscalls vereisen dat claimstatus en huidig endpoint overeenkomen. Een omgezet paneel of een handmatig ingevulde provider_mapping zonder claimrij wordt zonder netwerkcall geweigerd. Beëindigen bewaart de rij als terminated.
  • Het gegenereerde gebruikers- en serverwachtwoord worden één keer verstuurd en nooit opgeslagen, gelogd of teruggegeven. Klanten stellen hun eigen wachtwoord in via de wachtwoordreset van Convoy.

Configuratiecontract

Veld Type Verplicht Geheim Standaard
api_url string Ja Nee Leeg
api_token string Ja Ja Leeg
verify_tls boolean Nee Nee true
timeout string Nee Nee "20"

api_token moet een application API-token van een Convoy-beheerder zijn. timeout is standaard 20 seconden. Bewaar geheime waarden alleen in de beschermde extension-instellingen, nooit in productbeschrijvingen, URL's, screenshots of gedeelde voorbeelden.

Bekijk het pakket

Bronnen

Doorzoek de documentatie

Zoek handleidingen, commando’s en API-endpoints

Waar ben je naar op zoek?

Documentatie