Strom und Fernzugriff über die API

Diese Aufrufe kommunizieren mit dem Verwaltungscontroller des Servers und funktionieren daher auch bei nicht laufendem Betriebssystem. Stromstatus und Sensorwerte werden auch bei ausgeschaltetem Server zurückgegeben. Die serverbezogenen Aufrufe liegen unter /v1/baremetal/{serviceId}, die ISO-Bibliothek unter /v1/assets/isos.

Strom

Der Stromstatus ist powerState bei Dienststatus abrufen: ON, OFF, UNKNOWN oder BMC_RESETTING. UNKNOWN bedeutet, dass der Verwaltungscontroller nicht antwortete oder der Server keinen besitzt. Das Schema führt auch PENDING auf, was dieser Aufruf nie zurückgibt.

Strombefehl senden benötigt einen command:

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/power \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "command": "GRACEFUL_RESTART"
}
'

Der Aufruf antwortet mit 204 ohne Body; andere command-Werte mit 400 VALIDATION_ERROR. Ein regulärer Befehl setzt voraus, dass das Betriebssystem darauf reagiert. Bleibt ein Server nach GRACEFUL_SHUTDOWN ON, hat das Betriebssystem die Aufforderung nicht ausgeführt; der nächste Schritt ist FORCE_OFF.

Ein Strombefehl wird folgendermaßen abgelehnt:

Hardwarewerte

Drei schreibgeschützte Aufrufe liefern Controller-Messwerte auf Servern, deren hardware.capabilities den passenden Eintrag METRICS_* enthält. Andere Server antworten mit 422 OPERATION_NOT_SUPPORTED_PLATFORM:

• Netzteilzustand abrufen (METRICS_PSU) listet jedes Netzteil mit lineInputVoltage, powerInputWatts und status auf.
• Temperaturwerte abrufen (METRICS_THERMALS) liefert temperatures, jeweils mit readingCelsius und kritischen Schwellen, sowie fans, jeweils mit einem reading in readingUnits.
• Strommesswerte abrufen (METRICS_POWER) liefert den aktuellen Verbrauch als powerConsumedWatts und unter powerMetrics Minimum, Maximum und Durchschnitt der letzten intervalInMin Minuten.

Jeder status der ersten beiden Aufrufe besteht aus zwei Werten: dem Komponenten-state, etwa ENABLED oder ABSENT, und health mit OK, WARNING, CRITICAL oder UNKNOWN.

Treten hier Zeitüberschreitungen auf oder lässt sich keine Konsolensitzung öffnen, startet BMC zurücksetzen den Verwaltungscontroller neu, ohne den laufenden Server anzutasten. Die Antwort ist 204; powerState zeigt bis zur Rückkehr des Controllers BMC_RESETTING. Währenddessen antworten Strombefehle, Vorgänge, Konsolensitzungen und virtuelle Medien mit 409 BMC_RESET_IN_PROGRESS.

Konsolensitzungen

Eine Konsolensitzung öffnet Bildschirm und Tastatur des Servers im Browser, wenn dessen hardware.capabilities KVM oder IPMI enthält; andernfalls antwortet der Aufruf mit 422 OPERATION_NOT_SUPPORTED_PLATFORM. Die Sitzung ist eine Portweiterleitung zum Verwaltungscontroller, die nur Verbindungen von der in clientIpAddress genannten Adresse annimmt und sich nach timeoutSeconds schließt, zwischen 3600 und 86.400 (1 bis 24 Stunden).

Geben Sie die öffentliche IPv4- oder IPv6-Adresse des Rechners an, von dem aus Sie die Konsole öffnen. Hinter einem NAT-Router ist dies dessen öffentliche Adresse, die etwa eine IP-Auskunftswebsite oder die Statusseite des Routers zeigt. Verwenden Sie sie in Konsolensitzung öffnen:

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/console-sessions \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clientIpAddress": "<your-ip>",
  "timeoutSeconds": 7200
}
'

Die Antwort ist 201 mit der zu öffnenden url, forwardId, startedAt und expiresAt der Sitzung. Bei Servern mit IPMI enthält sie auch ipmiUsername und ipmiPassword für die Anmeldeseite des Controllers; bei KVM (Dell iDRAC9 und iDRAC10, Supermicro Gen12) sind beide null. Eine zweite Anfrage während des Sitzungsaufbaus antwortet mit 409 KVM_SESSION_REQUEST_IN_PROGRESS; wiederholen Sie nach Retry-After (10 Sekunden). Eine neue Sitzung von derselben Adresse verwendet die forwardId der offenen Sitzung erneut; ihr expiresAt ersetzt das vorherige.

Konsolensitzungen auflisten zeigt offene Sitzungen Ihrer Organisation, jeweils mit url, clientIpAddress, timeoutSeconds und expiresAt. Übergeben Sie zum vorzeitigen Schließen die forwardId an Konsolensitzung schließen. Der Aufruf antwortet mit 204, auch bei bereits geschlossener Sitzung:

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

Eine Sitzung von einem Rechner mit anderer öffentlicher Adresse als der erlaubten stellt keine Verbindung her. Öffnen Sie eine neue Sitzung mit der richtigen Adresse, statt die alte zu erweitern.

Virtuelle Medien

Virtuelle Medien verbinden eine ISO-Datei als Laufwerk mit dem Server, um ein nicht in der Imageliste angebotenes Installations- oder Rettungssystem zu starten. Dies funktioniert bei VIRTUAL_MEDIA in hardware.capabilities; Supermicro Gen11 und ASRock antworten auf Einbindungen mit 422 und OPERATION_NOT_SUPPORTED_PLATFORM. Das ISO muss zuerst in Ihrer Bibliothek liegen.

ISO hochladen

Ein Upload benötigt drei Aufrufe; die Datei selbst geht direkt an den Speicher, nicht durch die API:

1. ISO-Upload starten mit einem displayName von 3 bis 64 Zeichen und der exakten Dateigröße sizeBytes (höchstens 20.971.520.000 Byte, entsprechend 2.000 Teilen). Die Antwort ist 201 mit der ISO-id, totalParts und einem vorsignierten uploadUrls-Eintrag pro Teil.
2. Teilen Sie die Datei in 10-MiB-Teile (10.485.760 Byte; der letzte Teil enthält den Rest) und senden Sie Teil n per PUT an die n-te URL. Die URLs laufen zwei Stunden nach Ausstellung ab.
3. ISO-Upload abschließen. Sobald die hochgeladenen Teile die deklarierte Größe ergeben, antwortet der Aufruf mit 200 und der ISO-Datei. Ihr isReady wird dort und in ISOs auflisten true. Fehlende Daten führen zu 422 ISO_UPLOAD_INCOMPLETE, ein Speicherausfall zu 503 UPSTREAM_UNAVAILABLE.

stat -c %s installer.iso gibt die zu sendende Größe aus (stat -f %z unter macOS):

curl --request POST \
  --url https://api.serverside.com/v1/assets/isos \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "displayName": "rescue",
  "sizeBytes": 734003200
}
'

Mit der als upload.json gespeicherten Antwort teilt diese Shellschleife die Datei und sendet jeden Teil an seine URL:

split -b 10485760 -d -a 4 installer.iso part-
i=0
for url in $(jq -r '.data.uploadUrls[]' upload.json); do
  curl -s -X PUT --upload-file "part-$(printf '%04d' $i)" "$url"
  i=$((i + 1))
done

split -d ist die GNU-Form; verwenden Sie unter macOS gsplit. Schließen Sie dann den Upload mit der ISO-id ab:

curl --request POST \
  --url https://api.serverside.com/v1/assets/isos/{isoId}/complete-upload \
  --header 'Authorization: Bearer <api-key>'

Die zulässige Anzahl ISO-Dateien einer Organisation ist baremetal.maxIsoFiles bei Berechtigte Funktionen abrufen; null bedeutet unbegrenzt. Nie abgeschlossene Uploads zählen mit. Sobald die Organisation mehr Dateien als das Limit hält, antwortet ein neuer Upload mit 422 ISO_LIMIT_REACHED. ISO löschen gibt einen Platz frei; ein eingebundenes ISO kann nicht gelöscht werden (409 ENTITY_IN_USE).

Einbinden

Virtuelle Medien einbinden akzeptiert die ISO-ID als isoFileId und expirySeconds zwischen 1800 und 43.200 (30 Minuten bis 12 Stunden). Ein ISO mit unvollständigem Upload wird mit 422 ISO_UPLOAD_INCOMPLETE abgelehnt.

curl --request POST \
  --url https://api.serverside.com/v1/baremetal/{serviceId}/virtual-media \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "isoFileId": "<iso-id>",
  "expirySeconds": 3600,
  "isOneTimeBoot": true
}
'

Der Aufruf antwortet mit 201 und deviceIndex, isoFileId und expiresAt der Einbindung. Mit isOneTimeBoot true startet derselbe Aufruf den Server einmal vom ISO: Ein ausgeschalteter Server wird eingeschaltet, ein laufender sofort neu gestartet, ohne das Betriebssystem zum Herunterfahren aufzufordern. Verfolgen Sie die Installation über eine Konsolensitzung. Ohne diese Option wird das ISO als Laufwerk verbunden und die Startreihenfolge bleibt unverändert.

Ein Server hat jeweils eine Einbindung; eine neue ersetzt die letzte. Virtuelle Medien auflisten zeigt sie; ISOs eines Dienstes auflisten markiert die eingebundene Datei mit isMounted, mountExpiresAt und deviceIndex. Virtuelle Medien auswerfen trennt sie vor Ablauf und antwortet mit 204; ein Index ohne eingebundenes Medium wirft die erfasste Einbindung aus.