Déployer un serveur via l’API

Un script de déploiement sans surveillance nécessite plus que le démarrage rapide : une clé SSH enregistrée à l’avance, une configuration au premier démarrage, une attente de fin du déploiement et la lecture de l’opération en cas d’échec. Dans les exemples, <api-key> désigne votre clé API et un nom entre accolades comme {serviceId} un ID renvoyé précédemment.

1. Enregistrer une clé SSH

Une clé enregistrée dans l’organisation peut être installée sur tout serveur déployé. Ajouter une clé SSH accepte name et, dans publicKey, la ligne entière de votre fichier .pub (par exemple ~/.ssh/id_ed25519.pub). Les clés RSA, ED25519 et ECDSA sont acceptées.

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

L’appel répond 201 avec la clé enregistrée. Conservez son id ; Lister les clés SSH permet de la retrouver.

2. Obtenir le serveur

Choisissez une offre et un datacenter avec du stock, puis commandez et payez le serveur comme dans le démarrage rapide, qui aboutit à son ID. Une organisation disposant de la facturation horaire, indiquée par billing.isUsageBased à true dans Obtenir les droits, crée plutôt le service en un appel avec Créer un service bare metal. plan accepte l’id ou le slug de l’offre ; datacenter un code comme ams1 ou son ID. Générez la clé d’idempotence une seule fois (la sortie de uuidgen convient) et réutilisez-la lors d’une nouvelle tentative pour reconnaître une requête répétée après une erreur réseau :

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

L’appel répond 201 avec le nouveau service ; data.id est le {serviceId} des requêtes de déploiement, d’état et d’opération. Une nouvelle tentative avec la même clé répond 200 avec le serveur initial sans nouvelle création ; la même clé avec un corps différent donne 409 IDEMPOTENCY_KEY_REUSED. Sans facturation horaire, l’organisation reçoit 422 USAGE_BILLING_DISABLED.

Le serveur reçoit un /30 IPv4 et un /120 IPv6 sauf demande contraire (la facturation explique les tailles) ; le déploiement de l’étape 3 nécessite l’IPv4. bootMode et ipxeScript dans le même corps démarrent le serveur sur votre script iPXE plutôt qu’une image, comme l’expliquent les scripts iPXE personnalisés.

Une offre épuisée entre la liste et la commande est refusée avec 422 et OFFERING_NOT_AVAILABLE, par cet appel comme par une commande. Si une autre commande prend le dernier serveur juste après cette vérification, cet appel répond 409 PROVISIONING_FAILED ; listez à nouveau les offres avant de réessayer. Une commande par période ne réserve aucun serveur pendant l’impayé ; une offre épuisée avant paiement laisse donc la commande payée à FAILED, à provisionner ou rembourser par le support. Un refus de carte n’apparaît jamais ici : il figure dans le résultat de Payer une facture lors du paiement.

3. Déployer avec une configuration au premier démarrage

cloudInit accepte un document cloud-config, exécuté par le cloud-init de l’image au premier démarrage. Celui-ci installe deux paquets et crée un utilisateur :

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

La requête le transmet dans une chaîne JSON unique, chaque saut de ligne écrit \n. image accepte un id ou un slug de Lister les images système ; un slug comme ubuntu-24.04 choisit la première image active qui le porte.

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

L’appel répond 201 avec l’opération lancée, de type DEPLOYMENT ; conservez son id pour l’étape 5.

cloudInit concerne les images Linux. Un déploiement Windows accepte ce champ sans le lire ; un déploiement d’application le refuse. Sur une image Linux sans paquet cloud-init, le déploiement échoue à sa dernière étape, après écriture du disque.

La requête n’a pas de champ de nom d’hôte. Le système installé le tire du name du serveur : un nom d’hôte valide ou un nom de domaine pleinement qualifié est mis en minuscules ; tout autre nom devient une étiquette unique (minuscules, chaque autre caractère remplacé par -, 63 caractères maximum). Un nom sans caractère utilisable devient server- suivi des huit premiers caractères hexadécimaux de l’ID du service. Un renommage prend effet au prochain déploiement.

L’API vérifie la requête avant toute écriture ; une règle non respectée donne 422 VALIDATION_FAILED avec un détail la nommant :

Deux autres erreurs donnent des statuts différents. Un applicationMetadata qui n’est pas un objet JSON donne 400 VALIDATION_ERROR avec un détail INVALID_VALUE ; une entrée sshKeyIds qui n’est pas une clé de l’organisation donne 404 ENTITY_NOT_FOUND. Sans IPv4 principale, le serveur est refusé avec 422 PRIMARY_IPV4_REQUIRED avant les vérifications du tableau. Pendant une autre opération, modification réseau ou réinitialisation BMC, la requête répond 409 avec OPERATION_IN_PROGRESS, NETWORK_CHANGE_IN_PROGRESS ou BMC_RESET_IN_PROGRESS.

4. Attendre la fin

Pendant une opération, le state du service vaut OPERATION_IN_PROGRESS. Appelez Obtenir l’état du service environ toutes les 20 secondes jusqu’à ce que cet état change :

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

Entre les interrogations, data.operation.lastProgressMessage nomme l’étape atteinte. Une fois l’état changé, data.lastOperation.state indique le résultat : COMPLETED signifie que le serveur est installé. Son adresse est primaryIpv4 dans Obtenir un service bare metal ; operatingSystem.username est l’utilisateur de connexion : le username demandé, ou le defaultUser de l’image si omis. Les images Windows créent toujours Administrator avec le password demandé et n’acceptent pas les clés SSH.

Pour votre première connexion interactive, suivez Se connecter en RDP sous Windows ou Se connecter en SSH sous Linux. Utilisez le mot de passe défini ou la clé sélectionnée au déploiement ; Serverside.com ne conserve pas votre mot de passe de déploiement.

5. En cas d’échec du déploiement

Une opération FAILED conserve sa trace. Obtenir une opération avec son id renvoie failureCategory, lastProgressMessage et updates : tous les rapports de progression avec leur heure (at), progress et message. details reprend les paramètres : operatingSystem ou application, raidVariant et username.

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

La plateforme définit elle-même ces catégories :

Une application dont l’installation échoue après l’étape du système signale SCRIPT_DOWNLOAD_FAILED, SCRIPT_CHECKSUM_MISMATCH ou INSTALL_SCRIPT_FAILED : programme d’installation non téléchargeable, empreinte différente de celle enregistrée ou sortie en erreur. Le système reste installé et accessible ; /var/log/cloud-init-output.log contient la sortie du programme. Un échec pendant l’installation du système indique actuellement failureCategory à UNKNOWN. lastProgressMessage et les dernières updates permettent alors de distinguer une étape disque ou RAID d’un téléchargement d’image inachevé.

Un nouveau déploiement peut démarrer dès que le service revient à ACTIVE. Si la seconde tentative échoue à la même étape, contactez le support via le formulaire de la console cloud ou à tech@serverside.com. Le formulaire ne rattache pas le service : nommez le serveur dans le message et indiquez l’id de l’opération, sa failureCategory et son lastProgressMessage.