Alimentation et accès distant via l’API

Ces appels communiquent avec le contrôleur de gestion du serveur : ils fonctionnent lorsque le système est arrêté et renvoient l’état d’alimentation et les capteurs même serveur éteint. Les appels du serveur sont sous /v1/baremetal/{serviceId} ; la bibliothèque ISO se trouve à /v1/assets/isos.

Alimentation

L’état d’alimentation est powerState dans Obtenir l’état du service : ON, OFF, UNKNOWN ou BMC_RESETTING. UNKNOWN signifie que le contrôleur ne répond pas ou que le serveur n’en possède pas. Le schéma liste aussi PENDING, jamais renvoyé par cet appel.

Envoyer une commande d’alimentation exige 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"
}
'

L’appel répond 204 sans corps ; toute autre valeur de command donne 400 VALIDATION_ERROR. Une commande normale dépend de la réponse du système. Un serveur restant à ON après GRACEFUL_SHUTDOWN indique que son système n’a pas exécuté la demande ; FORCE_OFF est l’étape suivante.

Une commande d’alimentation est refusée avec :

Mesures matérielles

Trois appels en lecture seule fournissent les mesures du contrôleur lorsque hardware.capabilities contient l’entrée METRICS_* correspondante ; sinon ils répondent 422 OPERATION_NOT_SUPPORTED_PLATFORM :

• Obtenir l’état des PSU (METRICS_PSU) liste chaque alimentation avec lineInputVoltage, powerInputWatts et status.
• Obtenir les mesures thermiques (METRICS_THERMALS) renvoie temperatures, chaque readingCelsius et ses seuils critiques, ainsi que fans, chaque reading dans ses readingUnits.
• Obtenir les métriques d’alimentation (METRICS_POWER) donne la consommation actuelle dans powerConsumedWatts, et sous powerMetrics le minimum, maximum et la moyenne sur les dernières intervalInMin minutes.

Chaque status des deux premiers est une paire : state du composant, comme ENABLED ou ABSENT, et health, qui vaut OK, WARNING, CRITICAL ou UNKNOWN.

Si ces appels dépassent les délais, ou si une session console ne s’ouvre pas, Réinitialiser le BMC redémarre le contrôleur sans toucher au serveur en fonctionnement. L’appel répond 204 ; powerState reste à BMC_RESETTING jusqu’au retour du contrôleur. Entre-temps, commandes d’alimentation, opérations, sessions console et supports virtuels répondent 409 BMC_RESET_IN_PROGRESS.

Sessions console

Une session console ouvre l’écran et le clavier dans votre navigateur sur un serveur dont hardware.capabilities contient KVM ou IPMI ; sinon l’appel répond 422 OPERATION_NOT_SUPPORTED_PLATFORM. La session est une redirection de port vers le contrôleur, n’acceptant que l’adresse clientIpAddress ; elle se ferme après timeoutSeconds, de 3600 à 86 400 (1 à 24 heures).

Indiquez l’adresse publique IPv4 ou IPv6 de la machine depuis laquelle vous ouvrirez la console. Derrière un routeur NAT, il s’agit de l’adresse publique du routeur, visible sur un site de recherche d’IP ou sa page d’état. Ouvrez une session console avec cette adresse :

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

L’appel répond 201 avec l’url à ouvrir, forwardId, startedAt et expiresAt. Sur un serveur avec la capacité IPMI, il contient aussi ipmiUsername et ipmiPassword pour la page de connexion du contrôleur ; avec KVM (Dell iDRAC9 et iDRAC10, Supermicro Gen12), les deux valent null. Une seconde demande pendant la configuration initiale répond 409 KVM_SESSION_REQUEST_IN_PROGRESS ; réessayez après Retry-After (10 secondes). Une nouvelle session depuis la même adresse réutilise le forwardId ouvert et remplace son expiresAt.

Lister les sessions console montre les sessions ouvertes par votre organisation avec url, clientIpAddress, timeoutSeconds et expiresAt. Pour fermer une session avant son expiration, transmettez son forwardId à Fermer une session console ; l’appel répond 204, même si elle est déjà fermée :

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

Une session ouverte depuis une adresse publique différente de celle autorisée ne se connectera pas. Ouvrez une nouvelle session avec la bonne adresse plutôt que d’élargir l’ancienne.

Supports virtuels

Les supports virtuels rattachent une ISO comme lecteur au serveur pour démarrer un programme d’installation ou système de secours absent des images. Ils fonctionnent lorsque hardware.capabilities contient VIRTUAL_MEDIA ; les machines Supermicro Gen11 et ASRock répondent au montage avec 422 OPERATION_NOT_SUPPORTED_PLATFORM. L’ISO doit d’abord se trouver dans votre bibliothèque.

Téléverser une ISO

Le téléversement nécessite trois appels ; le fichier va directement au stockage sans transiter par l’API :

1. Démarrez le téléversement ISO avec displayName de 3 à 64 caractères et la taille exacte sizeBytes (au maximum 20 971 520 000 octets, soit 2 000 parties). La réponse 201 contient l’id de l’ISO, totalParts et une entrée uploadUrls présignée par partie.
2. Découpez le fichier en parties de 10 Mio (10 485 760 octets ; la dernière contient le reste) et envoyez la partie n par PUT à la nième URL. Les URL expirent deux heures après émission.
3. Terminez le téléversement ISO. Si la somme des parties correspond à la taille déclarée, la réponse 200 contient le fichier ; isReady passe à true ici et dans Lister les ISO. Des parties insuffisantes donnent 422 ISO_UPLOAD_INCOMPLETE ; une panne du stockage donne 503 UPSTREAM_UNAVAILABLE.

stat -c %s installer.iso affiche la taille à envoyer (stat -f %z sous 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
}
'

Une fois la réponse enregistrée dans upload.json, cette boucle shell découpe le fichier et envoie chaque partie à son 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 est la forme GNU ; sous macOS, utilisez gsplit. Terminez ensuite le téléversement avec l’id de l’ISO :

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

Le nombre de fichiers ISO autorisé est baremetal.maxIsoFiles dans Obtenir les droits, où null signifie sans limite. Les téléversements jamais terminés comptent ; dès que l’organisation possède plus de fichiers que la limite, un nouveau téléversement répond 422 ISO_LIMIT_REACHED. Supprimer une ISO libère une place ; une ISO montée ne peut être supprimée (409 ENTITY_IN_USE).

Monter l’ISO

Monter un support virtuel accepte l’ID de l’ISO dans isoFileId et expirySeconds entre 1800 et 43 200 (30 minutes à 12 heures). Une ISO dont le téléversement est inachevé est refusée avec 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
}
'

L’appel répond 201 avec deviceIndex, isoFileId et expiresAt. Avec isOneTimeBoot à true, il démarre aussi le serveur une fois sur l’ISO : il allume un serveur arrêté et redémarre immédiatement un serveur actif sans demander l’arrêt du système. Suivez l’installation dans une session console. Sans cette option, l’ISO est rattachée comme lecteur et l’ordre de démarrage reste inchangé.

Un serveur accepte un seul montage à la fois ; un nouveau remplace le précédent. Lister les supports virtuels l’affiche ; Lister les ISO d’un service marque le fichier monté avec isMounted, mountExpiresAt et deviceIndex. Éjecter un support virtuel le détache avant expiration et répond 204 ; un index sans montage éjecte le montage enregistré.