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
- Activeer de Provisioning Module en installeer en activeer daarna Convoy in Admin > Extensies.
- Sla
api_urlop alsscheme://host[:port]zonder pad, bijvoorbeeldhttps://convoy.example.com, en de application API-token van de beheerder inapi_token. De token wordt versleuteld opgeslagen. - Laat
verify_tlsaan. - Voer Test connection uit. Die roept de alleen-lezen
GET /servers?per_page=1aan. - 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 demain-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 oprevision. - 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
422en laat de claim falen. - Een
422bij het aanmaken van gebruiker of server, geweigerde inloggegevens of een fout vóór verzending bewijzen dat er niets is aangemaakt. De claim wordtfaileden een nieuwe poging maakt opnieuw aan, met behoud van een vastgelegde gebruiker. Timeouts, andere fouten en onverwachte bodies laten de claim opunknownstaan. 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_mappingzonder claimrij wordt zonder netwerkcall geweigerd. Beëindigen bewaart de rij alsterminated. - 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.