Voeding en externe toegang via de API

Deze aanroepen communiceren met de beheercontroller van de server. Ze werken dus terwijl het besturingssysteem uitstaat en geven ook bij een uitgeschakelde server de voedingsstatus en sensormetingen terug. De serveraanroepen staan onder /v1/baremetal/{serviceId}; de ISO-bibliotheek onder /v1/assets/isos.

Voeding

De voedingsstatus staat in powerState bij Dienststatus ophalen: ON, OFF, UNKNOWN of BMC_RESETTING. UNKNOWN betekent dat de beheercontroller niet antwoordde of dat de server er geen heeft. Het schema noemt ook PENDING, maar deze aanroep geeft die waarde nooit terug.

Voedingsopdracht versturen vereist 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"
}
'

De aanroep antwoordt met 204 zonder body. Elke andere waarde voor command geeft 400 VALIDATION_ERROR. Een normale opdracht vereist dat het besturingssysteem reageert. Als een server na GRACEFUL_SHUTDOWN op ON blijft, heeft het besturingssysteem de opdracht niet uitgevoerd en is FORCE_OFF de volgende stap.

Een voedingsopdracht wordt geweigerd met:

Hardwaremetingen

Drie alleen-lezenaanroepen geven de metingen van de controller terug als hardware.capabilities de bijbehorende METRICS_*-vermelding bevat. Anders antwoorden ze met 422 OPERATION_NOT_SUPPORTED_PLATFORM:

• PSU-status ophalen (METRICS_PSU) vermeldt elke voeding met lineInputVoltage, powerInputWatts en status.
• Temperatuurmetingen ophalen (METRICS_THERMALS) geeft temperatures, elk met readingCelsius en kritieke drempels, en fans, elk met een reading in readingUnits.
• Voedingsmetingen ophalen (METRICS_POWER) geeft het huidige verbruik als powerConsumedWatts en onder powerMetrics het minimale, maximale en gemiddelde verbruik gedurende de laatste intervalInMin minuten.

Elke status in de eerste twee bestaat uit twee waarden: de state van de component, zoals ENABLED of ABSENT, en de health: OK, WARNING, CRITICAL of UNKNOWN.

Als deze aanroepen time-outs geven of een consolesessie niet opent, herstart BMC resetten de beheercontroller zonder de draaiende server te wijzigen. Het antwoord is 204; powerState blijft BMC_RESETTING totdat de controller terug is. Ondertussen antwoorden voedingsopdrachten, bewerkingen, consolesessies en virtuele media met 409 BMC_RESET_IN_PROGRESS.

Consolesessies

Een consolesessie opent het scherm en toetsenbord van de server in uw browser als hardware.capabilities KVM of IPMI bevat. Anders antwoordt de aanroep met 422 OPERATION_NOT_SUPPORTED_PLATFORM. De sessie is een poortdoorsturing naar de beheercontroller die alleen verbindingen van clientIpAddress accepteert. Ze sluit automatisch na timeoutSeconds, van 3600 tot 86.400 (1 tot 24 uur).

Geef het openbare IPv4- of IPv6-adres op van de machine waarmee u de console opent. Achter een NAT-router is dat het openbare routeradres, te vinden op een website die uw IP toont of op de statuspagina van de router. Roep hiermee Consolesessie openen aan:

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

De aanroep antwoordt met 201 en de te openen url, forwardId, startedAt en expiresAt. Op een server met IPMI bevat het antwoord ook ipmiUsername en ipmiPassword voor de inlogpagina van de controller. Op een server met KVM (Dell iDRAC9 en iDRAC10, Supermicro Gen12) zijn beide null. Een tweede verzoek terwijl het eerste nog wordt ingericht, antwoordt met 409 KVM_SESSION_REQUEST_IN_PROGRESS; probeer opnieuw na Retry-After (10 seconden). Een nieuwe sessie vanaf hetzelfde adres hergebruikt de forwardId van de open sessie en vervangt de eerdere expiresAt.

Consolesessies opvragen toont de open sessies van uw organisatie, elk met url, clientIpAddress, timeoutSeconds en expiresAt. Geef de forwardId door aan Consolesessie sluiten om een sessie eerder te sluiten. Het antwoord is 204, ook als de sessie al gesloten is:

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

Een sessie vanaf een machine met een ander openbaar adres dan toegestaan, maakt geen verbinding. Open een nieuwe sessie met het juiste adres in plaats van de oude ruimer open te stellen.

Virtuele media

Virtuele media koppelen een ISO-bestand als schijf aan de server, om een installatieprogramma of herstelsysteem te starten dat niet in de imagelijst staat. Dit werkt als hardware.capabilities VIRTUAL_MEDIA bevat. Supermicro Gen11- en ASRock-machines antwoorden op koppelen met 422 OPERATION_NOT_SUPPORTED_PLATFORM. De ISO moet eerst in uw bibliotheek staan.

Upload een ISO

Uploaden vereist drie aanroepen. Het bestand zelf gaat rechtstreeks naar de opslag en niet via de API:

1. ISO-upload starten met een displayName van 3 tot 64 tekens en de exacte sizeBytes van het bestand (maximaal 20.971.520.000 bytes, oftewel 2.000 delen). Het antwoord is 201 met de id van de ISO, totalParts en één vooraf ondertekende uploadUrls-vermelding per deel.
2. Splits het bestand in delen van 10 MiB (10.485.760 bytes; het laatste deel bevat de rest) en stuur deel n met PUT naar de nde URL. De URL’s verlopen twee uur na uitgifte.
3. ISO-upload voltooien. Zodra de delen samen de opgegeven grootte hebben, antwoordt dit met 200 en het ISO-bestand. De isReady wordt hier en bij ISO’s opvragen true. Te weinig geüploade data geeft 422 ISO_UPLOAD_INCOMPLETE; een opslagstoring geeft 503 UPSTREAM_UNAVAILABLE.

stat -c %s installer.iso toont de grootte die u moet versturen (stat -f %z op 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
}
'

Als het antwoord in upload.json staat, splitst deze shelllus het bestand en stuurt elk deel naar zijn 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 is de GNU-vorm; gebruik op macOS gsplit. Voltooi daarna de upload met de id van de ISO:

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

Het toegestane aantal ISO-bestanden is baremetal.maxIsoFiles bij Rechten ophalen; null betekent geen limiet. Onvoltooide uploads tellen mee. Zodra de organisatie meer bestanden heeft dan de limiet, antwoordt een nieuwe upload met 422 ISO_LIMIT_REACHED. ISO verwijderen maakt een plaats vrij; een gekoppelde ISO kan niet worden verwijderd (409 ENTITY_IN_USE).

Koppel de ISO

Virtuele media koppelen accepteert de ISO-ID als isoFileId en expirySeconds tussen 1800 en 43.200 (30 minuten tot 12 uur). Een ISO waarvan de upload nog niet is voltooid, wordt geweigerd met 422 ISO_UPLOAD_INCOMPLETE.

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

De aanroep antwoordt met 201 en deviceIndex, isoFileId en expiresAt van de koppeling. Met isOneTimeBoot op true start dezelfde aanroep de server één keer vanaf de ISO: een gestopte server wordt ingeschakeld, een draaiende server direct herstart zonder het besturingssysteem te vragen af te sluiten. Volg het installatieprogramma via een consolesessie. Zonder deze optie wordt de ISO als schijf gekoppeld en blijft de opstartvolgorde ongewijzigd.

Een server heeft één koppeling tegelijk; een nieuwe vervangt de vorige. Virtuele media opvragen toont deze. ISO’s voor een dienst opvragen markeert het gekoppelde bestand met isMounted, mountExpiresAt en deviceIndex. Virtuele media uitwerpen ontkoppelt vóór het verlopen en antwoordt met 204; een index zonder gekoppeld medium werpt de geregistreerde koppeling uit.