Server über die API bereitstellen

Ein unbeaufsichtigtes Bereitstellungsskript benötigt mehr als der Schnellstart zeigt: einen vorab gespeicherten SSH-Schlüssel, eine Erststartkonfiguration, das Warten auf den Abschluss und eine Möglichkeit, den Vorgang bei Fehlern zu lesen. In den Beispielen steht <api-key> für Ihren API-Schlüssel und ein Name in geschweiften Klammern wie {serviceId} für eine von einem früheren Schritt zurückgegebene ID.

1. SSH-Schlüssel speichern

Ein in der Organisation gespeicherter Schlüssel kann auf jedem bereitgestellten Server installiert werden. SSH-Schlüssel hinzufügen akzeptiert einen name und als publicKey die vollständige Zeile Ihrer .pub-Datei (etwa ~/.ssh/id_ed25519.pub). RSA-, ED25519- und ECDSA-Schlüssel werden akzeptiert.

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>"
}
'

Der Aufruf antwortet mit 201 und dem gespeicherten Schlüssel. Bewahren Sie seine id auf; über SSH-Schlüssel auflisten finden Sie ihn später wieder.

2. Server beziehen

Wählen Sie einen Tarif und ein Rechenzentrum mit Bestand, bestellen und bezahlen Sie den Server wie im Schnellstart, der mit dessen ID endet. Eine Organisation mit stündlicher Abrechnung, erkennbar an billing.isUsageBased true bei Berechtigte Funktionen abrufen, erstellt den Dienst stattdessen mit einem Aufruf von Bare-Metal-Dienst erstellen. plan akzeptiert die id oder den slug des Tarifs, datacenter einen Rechenzentrumscode wie ams1 oder die Rechenzentrums-ID. Erzeugen Sie den Idempotenzschlüssel einmal (etwa mit uuidgen) und senden Sie bei einer Wiederholung denselben Wert, damit eine nach einem Netzwerkfehler wiederholte Anfrage als dieselbe erkannt wird:

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"
}
'

Der Aufruf antwortet mit 201 und dem neuen Dienst. Dessen data.id ist die {serviceId} der Bereitstellungs-, Status- und Vorgangsanfragen. Eine Wiederholung mit demselben Schlüssel antwortet mit 200 und dem ursprünglich erstellten Server, ohne einen weiteren anzulegen. Derselbe Schlüssel mit anderem Body antwortet mit 409 IDEMPOTENCY_KEY_REUSED. Eine Organisation ohne stündliche Abrechnung erhält 422 USAGE_BILLING_DISABLED.

Der Server erhält ein IPv4-/30 und ein IPv6-/120, sofern die Anfrage nichts anderes verlangt (Abrechnung beschreibt die Größen). Die Bereitstellung in Schritt 3 benötigt die IPv4-Adresse. bootMode und ipxeScript im selben Body starten den Server mit Ihrem eigenen iPXE-Skript statt einem Image, wie unter Eigene iPXE-Skripte beschrieben.

Ist ein Tarif zwischen Auflistung und Bestellung ausverkauft, lehnen sowohl dieser Aufruf als auch eine Bestellung ihn mit 422 und OFFERING_NOT_AVAILABLE ab. Belegt eine andere Bestellung unmittelbar nach dieser Prüfung den letzten Server, antwortet dieser Aufruf mit 409 und PROVISIONING_FAILED; listen Sie vor einem erneuten Versuch die Tarife erneut auf. Eine Laufzeitbestellung reserviert keinen Server, solange ihre Rechnung unbezahlt ist. Ist der Tarif vor der Zahlung ausverkauft, bleibt die bezahlte Bestellung FAILED, bis der Support sie bereitstellt oder erstattet. Eine abgelehnte Karte erscheint nie in dieser Phase, sondern im Ergebnis von Rechnung bezahlen bei der Rechnungszahlung.

3. Mit Erststartkonfiguration bereitstellen

cloudInit akzeptiert ein cloud-config-Dokument, das cloud-init des Images beim ersten Start ausführt. Dieses installiert zwei Pakete und erstellt einen Benutzer:

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

Die Bereitstellungsanfrage übergibt es als einzelne JSON-Zeichenfolge, in der jeder Zeilenumbruch als \n geschrieben ist. image akzeptiert eine id oder einen slug aus Betriebssystemimages auflisten; ein Slug wie ubuntu-24.04 wählt das erste aktive Image mit diesem 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"
}
'

Der Aufruf antwortet mit 201 und dem gestarteten Vorgang vom type DEPLOYMENT; bewahren Sie seine id für Schritt 5 auf.

cloudInit ist für Linux-Images bestimmt. Eine Windows-Bereitstellung akzeptiert das Feld, liest es aber nie; eine Anwendungsbereitstellung lehnt es ab. Bei einem Linux-Image ohne cloud-init-Paket schlägt die Bereitstellung im letzten Schritt fehl, nachdem der Datenträger beschrieben wurde.

Die Anfrage hat kein Hostnamenfeld. Das installierte System übernimmt seinen Hostnamen aus dem name des Servers: Ein gültiger Hostname oder vollständig qualifizierter Domainname wird kleingeschrieben verwendet; jeder andere Name wird zu einer einzelnen Bezeichnung umgewandelt (Kleinschreibung, jedes andere Zeichen durch - ersetzt, maximal 63 Zeichen). Bleibt nichts Nutzbares, wird server- gefolgt von den ersten acht Hexadezimalzeichen der Dienst-ID verwendet. Eine Umbenennung wird bei der nächsten Bereitstellung wirksam.

Die API prüft die Anfrage, bevor Daten geschrieben werden. Verletzt sie eine dieser Regeln, wird sie mit 422 VALIDATION_FAILED und einem benennenden Detail abgelehnt:

Zwei weitere Fehler antworten mit anderen Statuscodes. Ein applicationMetadata, das kein JSON-Objekt ist, antwortet mit 400 VALIDATION_ERROR und einem Detail INVALID_VALUE; ein sshKeyIds-Eintrag, der kein Schlüssel der Organisation ist, mit 404 ENTITY_NOT_FOUND. Ein Server ohne primäre IPv4-Adresse wird vor allen Tabellenprüfungen mit 422 PRIMARY_IPV4_REQUIRED abgelehnt. Während eines anderen Vorgangs, einer Netzwerkänderung oder eines BMC-Resets antwortet die Anfrage mit 409 und OPERATION_IN_PROGRESS, NETWORK_CHANGE_IN_PROGRESS beziehungsweise BMC_RESET_IN_PROGRESS.

4. Auf Abschluss warten

Während eines Vorgangs ist der state des Dienstes OPERATION_IN_PROGRESS. Senden Sie etwa alle 20 Sekunden Dienststatus abrufen, bis sich dies ändert:

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

Zwischen den Abfragen nennt data.operation.lastProgressMessage die erreichte Bereitstellungsphase. Nach dem Statuswechsel zeigt data.lastOperation.state das Ergebnis: COMPLETED bedeutet, dass der Server installiert ist. Seine Adresse ist primaryIpv4 bei Bare-Metal-Dienst abrufen; operatingSystem.username dort ist der Anmeldebenutzer: der in der Anfrage genannte username oder ohne Angabe der defaultUser des Images. Windows-Images erstellen immer Administrator mit dem password der Anfrage und akzeptieren keine SSH-Schlüssel.

Folgen Sie für die erste interaktive Verbindung unter Windows Mit RDP verbinden, unter Linux Mit SSH verbinden. Verwenden Sie das bei der Bereitstellung gesetzte Passwort oder den ausgewählten SSH-Schlüssel; Serverside.com speichert Ihr Bereitstellungspasswort nicht.

5. Wenn eine Bereitstellung fehlschlägt

Ein Vorgang mit FAILED behält seine Historie. Vorgang abrufen mit dessen id liefert failureCategory, lastProgressMessage und updates: alle gesendeten Fortschrittsmeldungen mit Zeit (at), progress und message. details wiederholt die Bereitstellungsparameter: operatingSystem oder application, raidVariant und username.

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

Die Plattform setzt diese Kategorien selbst:

Schlägt die Anwendungsinstallation nach der Betriebssystemphase fehl, meldet sie SCRIPT_DOWNLOAD_FAILED, SCRIPT_CHECKSUM_MISMATCH oder INSTALL_SCRIPT_FAILED: Ihr Installationsprogramm konnte nicht heruntergeladen werden, entsprach nicht seinem gespeicherten Hash oder endete mit einem Fehler. Das Betriebssystem bleibt dann installiert und erreichbar; /var/log/cloud-init-output.log auf dem Server enthält die Installationsausgabe. Ein Fehler während der Betriebssysteminstallation meldet derzeit failureCategory UNKNOWN. lastProgressMessage und die letzten updates unterscheiden dann einen Datenträger- oder RAID-Schritt von einem nicht abgeschlossenen Imagedownload.

Eine neue Bereitstellung kann starten, sobald der Dienst wieder ACTIVE ist. Scheitert der zweite Versuch in derselben Phase, kontaktieren Sie den Support über das Formular der Cloud-Konsole oder unter tech@serverside.com. Das Formular verknüpft den Dienst nicht automatisch: Nennen Sie deshalb den Server in der Nachricht und geben Sie id, failureCategory und lastProgressMessage des Vorgangs an.