Automatiseringsworkflows

Een server uitrollen via de API

Van een SSH-sleutel naar een server waarop u kunt inloggen, met het volgen van de implementatie en het onderzoeken van fouten.

Een script dat zonder toezicht uitrolt, heeft meer nodig dan de snelstart laat zien: een vooraf opgeslagen SSH-sleutel, configuratie bij de eerste start, wachten tot de implementatie klaar is en een manier om de bewerking bij fouten uit te lezen. In de voorbeelden staat <api-key> voor uw API-sleutel en een naam tussen accolades, zoals {serviceId}, voor een ID uit een eerdere stap.

1. Sla een SSH-sleutel op

Een sleutel die in de organisatie is opgeslagen, kan op elke server worden geplaatst die u uitrolt. SSH-sleutel toevoegen accepteert een name en als publicKey de hele regel uit uw .pub-bestand, bijvoorbeeld ~/.ssh/id_ed25519.pub. RSA-, ED25519- en ECDSA-sleutels worden geaccepteerd.

curl --request POST \
  --url https://api.serverside.com/v1/organization/ssh-keys \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "laptop",
  "publicKey": "<public-key>"
}
'

De aanroep antwoordt met 201 en de opgeslagen sleutel. Bewaar de id; met SSH-sleutels opvragen vindt u deze later terug.

2. Verkrijg de server

Kies een abonnement en datacenter met voorraad en bestel en betaal de server zoals in de snelstart, die eindigt met zijn ID. Een organisatie met facturering per uur, aangegeven door billing.isUsageBased op true bij Rechten ophalen, maakt de dienst in plaats daarvan in één aanroep aan met Dedicated server aanmaken. plan accepteert de id of slug van het abonnement; datacenter een code zoals ams1 of de datacenter-ID. Genereer de idempotentiesleutel één keer (de uitvoer van uuidgen volstaat) en gebruik dezelfde waarde bij een nieuwe poging, zodat een verzoek na een netwerkfout als hetzelfde verzoek wordt herkend:

curl --request POST \
  --url https://api.serverside.com/v1/baremetal \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "plan": "<plan-id>",
  "datacenter": "<datacenter-code>",
  "name": "web-1"
}
'

De aanroep antwoordt met 201 en de nieuwe dienst; data.id is de {serviceId} voor de implementatie-, status- en bewerkingsverzoeken. Een nieuwe poging met dezelfde sleutel antwoordt met 200 en de eerder aangemaakte server, zonder iets nieuws te bestellen. Dezelfde sleutel met een andere body antwoordt met 409 IDEMPOTENCY_KEY_REUSED. Een organisatie zonder facturering per uur krijgt 422 USAGE_BILLING_DISABLED.

De server krijgt een IPv4 /30 en IPv6 /120, tenzij het verzoek iets anders vraagt (Facturering beschrijft de groottes). De implementatie in stap 3 heeft het IPv4-adres nodig. Met bootMode en ipxeScript in dezelfde body start de server via uw eigen iPXE-script in plaats van een image, zoals beschreven bij Eigen iPXE-scripts.

Een abonnement dat tussen opvragen en bestellen uitverkocht raakt, wordt geweigerd met 422 en OFFERING_NOT_AVAILABLE, zowel bij deze aanroep als bij een bestelling. Als een andere bestelling direct na die controle de laatste server neemt, antwoordt deze aanroep met 409 PROVISIONING_FAILED; vraag de abonnementen opnieuw op voordat u het nogmaals probeert. Een bestelling voor een vaste termijn reserveert geen server zolang de factuur onbetaald is. Raakt de voorraad vóór betaling op, dan blijft de betaalde bestelling op FAILED staan totdat support deze oplevert of terugbetaalt. Een geweigerde kaart verschijnt nooit in deze stap, maar bij het resultaat van Factuur betalen, tijdens de betaling.

3. Rol uit met configuratie bij de eerste start

cloudInit accepteert een cloud-configdocument dat de cloud-init van de image bij de eerste start uitvoert. Dit voorbeeld installeert twee pakketten en maakt een gebruiker aan:

#cloud-config
packages:
  - htop
  - fail2ban
users:
  - name: deploy
    groups: sudo
    shell: /bin/bash

Het implementatieverzoek bevat dit als één JSON-string, met elke regeleinde geschreven als \n. image accepteert een id of slug uit Besturingssysteemimages opvragen; een slug zoals ubuntu-24.04 kiest de eerste actieve image met die slug.

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/deploy \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "image": "<image-slug>",
  "sshKeyIds": [
    "<ssh-key-id>"
  ],
  "raidVariant": "RAID1",
  "cloudInit": "#cloud-config\npackages:\n  - htop\n  - fail2ban\nusers:\n  - name: deploy\n    groups: sudo\n    shell: /bin/bash"
}
'

De aanroep antwoordt met 201 en de gestarte bewerking, met type DEPLOYMENT; bewaar de id voor stap 5.

cloudInit is bedoeld voor Linux-images. Een Windows-implementatie accepteert het veld maar leest het niet; een implementatie die een applicatie installeert, weigert het. Op een Linux-image zonder het cloud-initpakket mislukt de laatste implementatiestap, nadat de schijf al is beschreven.

Het verzoek heeft geen hostnaamveld. Het geïnstalleerde systeem ontleent zijn hostnaam aan de name van de server. Een geldige hostnaam of volledig gekwalificeerde domeinnaam wordt in kleine letters gebruikt; elke andere naam wordt één label (kleine letters, alle overige tekens vervangen door -, maximaal 63 tekens). Blijft er niets bruikbaars over, dan wordt de naam server- gevolgd door de eerste acht hexadecimale tekens van de dienst-ID. Een naamswijziging gaat bij de volgende implementatie in.

De API controleert het verzoek voordat iets wordt geschreven. Een verzoek dat een van deze regels schendt, wordt geweigerd met 422 VALIDATION_FAILED en een detail dat de regel benoemt:

Detail `code`	Regel
`LOGIN_CREDENTIAL_REQUIRED`	De server heeft een inlogmethode nodig. Linux accepteert een `password`, SSH-sleutel of `cloudInit`-document; Windows vereist een `password`.
`DEPLOY_SELECTION_INVALID`	Het verzoek noemt zowel `image` als `application`, of geen van beide.
`OPERATING_SYSTEM_NOT_FOUND`, `APPLICATION_NOT_FOUND`	Geen image of applicatie heeft die ID of slug.
`OPERATING_SYSTEM_UNAVAILABLE`	De image is ingetrokken, of alle images met die slug zijn ingetrokken.
`APPLICATION_UNAVAILABLE`	De applicatie is ingetrokken of geen huidige image kan deze uitvoeren.
`APPLICATION_METADATA_UNSUPPORTED`, `APPLICATION_METADATA_INVALID`	`applicationMetadata` is verstuurd zonder applicatie, voor een applicatie die geen metadata accepteert, of voldoet niet aan het `metadataSchema`.
`RAID_VARIANT_UNSUPPORTED`	De image biedt die `raidVariant` niet aan. RAID is alleen beschikbaar voor Linux-images.
`RAID_DRIVE_COUNT_UNSUPPORTED`	De server heeft te weinig schijven voor die `raidVariant` (twee voor `RAID0` en `RAID1`, drie voor `RAID5`, vier voor `RAID6` en `RAID10`), of een oneven aantal voor `RAID10`.
`CLOUD_INIT_UNSUPPORTED`	`cloudInit` is met een applicatie verstuurd.

Twee andere fouten geven andere statussen. applicationMetadata dat geen JSON-object is, antwoordt met 400 VALIDATION_ERROR en een detail INVALID_VALUE. Een sshKeyIds-vermelding die geen sleutel van de organisatie is, geeft 404 ENTITY_NOT_FOUND. Een server zonder primair IPv4-adres wordt vóór de controles in de tabel geweigerd met 422 PRIMARY_IPV4_REQUIRED. Tijdens een andere bewerking, netwerkwijziging of BMC-reset antwoordt het verzoek met 409 en OPERATION_IN_PROGRESS, NETWORK_CHANGE_IN_PROGRESS of BMC_RESET_IN_PROGRESS.

4. Wacht tot de implementatie klaar is

Tijdens een bewerking is de state van de dienst OPERATION_IN_PROGRESS. Roep Dienststatus ophalen ongeveer elke 20 seconden aan totdat dit verandert:

curl --request GET \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/status \
  --header 'Authorization: Bearer <api-key>'

Tussen de controles noemt data.operation.lastProgressMessage de bereikte fase. Zodra de status verandert, geeft data.lastOperation.state de afloop aan: COMPLETED betekent dat de server is geïnstalleerd. Het adres is primaryIpv4 bij Dedicated server ophalen; operatingSystem.username is de inloggebruiker: de opgegeven username, of de defaultUser van de image als die ontbrak. Windows-images maken altijd Administrator aan met het opgegeven password en accepteren geen SSH-sleutels.

Volg voor uw eerste interactieve verbinding Verbinden met RDP voor Windows of Verbinden met SSH voor Linux. Gebruik het wachtwoord of de SSH-sleutel van de implementatie; Serverside.com bewaart uw implementatiewachtwoord niet.

5. Als een implementatie mislukt

Een bewerking met FAILED bewaart haar verloop. Bewerking ophalen met de bewerkings-id geeft failureCategory, lastProgressMessage en updates: elk voortgangsbericht met tijdstip (at), progress en message. details herhaalt de gebruikte instellingen: operatingSystem of application, raidVariant en username.

curl --request GET \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/operations/{operationId} \
  --header 'Authorization: Bearer <api-key>'

Het platform stelt deze categorieën zelf vast:

`failureCategory`	Gebeurtenis
`CHECK_IN_TIMED_OUT`	De server meldde zich na de netwerkboot niet aan; de installatie begon niet.
`NODE_PREPARE_FAILED`	De server kon niet op de installatie worden voorbereid.
`BMC_POWER_COMMAND_FAILED`	De beheercontroller kon de server niet uit- en inschakelen.
`CHECK_IN_PROFILE_BUILD_FAILED`	De server meldde zich aan, maar de installatie-instructies konden niet worden opgebouwd.
`CHECK_IN_INTERFACE_MISSING`	De server meldde zich aan zonder een poort waaraan een netwerk is gekoppeld.
`OPERATION_TIMED_OUT`	De implementatie was niet binnen de tijdslimiet klaar.

Een applicatie waarvan de installatie na de besturingssysteemfase mislukt, meldt SCRIPT_DOWNLOAD_FAILED, SCRIPT_CHECKSUM_MISMATCH of INSTALL_SCRIPT_FAILED: het installatieprogramma kon niet worden gedownload, kwam niet overeen met de opgeslagen hash of eindigde met een fout. Het besturingssysteem blijft dan geïnstalleerd en bereikbaar; /var/log/cloud-init-output.log bevat de uitvoer van het installatieprogramma. Een fout tijdens de installatie van het besturingssysteem meldt voorlopig failureCategory UNKNOWN. lastProgressMessage en de laatste updates onderscheiden dan een schijf- of RAID-stap van een onvoltooide imagedownload.

Een nieuwe implementatie kan starten zodra de dienst weer ACTIVE is. Mislukt de tweede poging in dezelfde fase, neem dan contact op met support via het formulier in de cloudconsole of via tech@serverside.com. Het formulier koppelt de dienst niet automatisch; noem de server in het bericht en voeg de id, failureCategory en lastProgressMessage van de bewerking toe.

1. Sla een SSH-sleutel op

2. Verkrijg de server

3. Rol uit met configuratie bij de eerste start

4. Wacht tot de implementatie klaar is

5. Als een implementatie mislukt

Voettekst