API OVHcloud et installation d'un OS

Objectif

Pour de nombreux cas d'usage, il peut s'avérer intéressant d'automatiser l'installation ou la réinstallation d'un système d'exploitation de vos serveurs dédiés à l'aide de l'API OVHcloud.

Prérequis

• Un serveur dédié dans votre compte OVHcloud
• Avoir accès à l'API OVHcloud

En pratique

Compatibilité OS

Connectez-vous sur https://api.ovh.com/ puis rendez-vous dans la section /dedicated/server.

Pour lister tous vos serveurs dédiés :

Vous pouvez lister les OS compatibles pour un serveur donné en utilisant l'appel suivant :

Regardez la liste retournée sous la clef ovh : il s'agit de la liste des OS du catalogue OVHcloud que vous pouvez installer.

Informations détaillées sur les OS

En allant dans la section /dedicated/installationTemplate, vous pouvez afficher les détails d'un OS en particulier :

Vous y trouverez des informations pertinentes comme par exemple :

¹ Les clients n'utilisant pas les images du catalogue OVHcloud (installation via une image personnalisée (BYOI/BYOLinux), installation par le réseau, ou manuellement avec l'IPMI) ne sont pas concernés par cette limitation.
² Pour plus d'informations, reportez-vous à la page personnaliser le partitionnement.

Questions spécifiques des OS

Certains OS peuvent avoir une liste de questions spécifiques. Si c'est le cas, la clef inputs contient une liste de questions.

Exemple de valeurs pour la clef inputs pour Debian 12 (Bookworm) :

{
    "inputs": [
        {
            "name": "hostname",
            "description": "Custom hostname",
            "default": "",
            "mandatory": false,
            "type": "hostname",
            "enum": []
        },
        {
            "name": "sshKey",
            "description": "SSH Public Key",
            "default": "",
            "mandatory": false,
            "type": "sshPubKey",
            "enum": []
        },
        {
            "name": "postInstallationScript",
            "description": "Post-Installation Script",
            "default": "",
            "mandatory": false,
            "type": "text",
            "enum": []
        }
    ]
}

Exemple de valeurs pour la clef inputs pour Windows Server 2022 Standard (Core) :

{
    "inputs": [
        {
            "name": "language",
            "description": "Display Language",
            "default": "en-us",
            "mandatory": false,
            "type": "enum",
            "enum": [
                "en-us",
                "fr-fr"
            ]
        },
        {
            "name": "postInstallationScript",
            "description": "Post-Installation Script",
            "default": "",
            "mandatory": false,
            "type": "text",
            "enum": []
        },
        {
            "name": "postInstallationScriptExtension",
            "description": "Post-Installation Script File Extension",
            "default": "ps1",
            "mandatory": true,
            "type": "enum",
            "enum": [
                "ps1",
                "cmd"
            ]
        }
    ]
}

Chaque question a les attributs suivants :

¹ Si une question obligatoire ne possédant pas de valeur par défaut est laissée sans réponse, alors l'API retournera une erreur.

Lancer et suivre la demande de réinstallation

Lorsque vous avez rassemblé toutes les informations nécessaires, vous pouvez lancer la réinstallation de l'OS, en utilisant l'appel suivant :

Avec les paramètres suivants :

¹ Spécifique au système d'exploitation, certaines personnalisations peuvent être requises dans certains cas.

customizations contient une hash avec les réponses aux questions spécifiques à l'OS : la clé de la hash doit contenir le nom (name) de la question et sa valeur doit contenir la réponse à la question, dans le format qui correspond au type requis.

storage contient la configuration liée aux disques & RAID matériels, partitions, RAID logiciels, LVM, ZFS, etc. Voir API OVHcloud et Stockage pour plus de détails.

Exemple d'un payload pour installer Linux

Ce payload permet d'installer Debian 12 (Bookworm) avec une clé SSH publique et un script bash de post-installation.

{
  "operatingSystem": "debian12_64",
  "customizations": {
    "hostname": "mon-tux",
    "sshKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQC9xPpdqP3sx2H+gcBm65tJEaUbuifQ1uGkgrWtNY0PRKNNPdy+3yoVOtxk6Vjo4YZ0EU/JhmQfnrK7X7Q5vhqYxmozi0LiTRt0BxgqHJ+4hWTWMIOgr+C2jLx7ZsCReRk+fy5AHr6h0PHQEuXVLXeUy/TDyuY2JPtUZ5jcqvLYgQ== my-nuclear-power-plant",
    "postInstallationScript": "IyEvYmluL2Jhc2gKZWNobyAiY291Y291IHBvc3RJbnN0YWxsYXRpb25TY3JpcHQiID4gL29wdC9jb3Vjb3UKY2F0IC9ldGMvbWFjaGluZS1pZCAgPj4gL29wdC9jb3Vjb3UKZGF0ZSAiKyVZLSVtLSVkICVIOiVNOiVTIiAtLXV0YyA+PiAvb3B0L2NvdWNvdQo="
  }
}

Même si le script de post-installation peut être envoyé à l'API en clair directement en échappant les bons caractères, il est recommandé d'envoyer à l'API le script encodé en base64 en utilisant par exemple la commande UNIX/Linux suivante :

cat my-script.sh | base64 -w0

Voici le script bash de post-installation en clair avec l'exemple ci-dessus :

#!/bin/bash
echo "coucou postInstallationScript" > /opt/coucou
cat /etc/machine-id  >> /opt/coucou
date "+%Y-%m-%d %H:%M:%S" --utc >> /opt/coucou

Exemple d'un payload pour installer Windows

Ce payload permet d'installer Windows Server 2022 Standard (Core) en français avec un script PowerShell de post-installation.

{
  "operatingSystem": "win2022core-std_64",
  "customizations": {
    "hostname": "ma-fenetre",
    "language": "fr-fr",
    "postInstallationScript": "ImNvdWNvdSBwb3N0SW5zdGFsbGF0aW9uU2NyaXB0UG93ZXJTaGVsbCIgfCBPdXQtRmlsZSAtRmlsZVBhdGggImM6XG92aHVwZFxzY3JpcHRcY291Y291LnR4dCIKKEdldC1JdGVtUHJvcGVydHkgLUxpdGVyYWxQYXRoICJSZWdpc3RyeTo6SEtMTVxTT0ZUV0FSRVxNaWNyb3NvZnRcQ3J5cHRvZ3JhcGh5IiAtTmFtZSAiTWFjaGluZUd1aWQiKS5NYWNoaW5lR3VpZCB8IE91dC1GaWxlIC1GaWxlUGF0aCAiYzpcb3ZodXBkXHNjcmlwdFxjb3Vjb3UudHh0IiAtQXBwZW5kCihHZXQtRGF0ZSkuVG9Vbml2ZXJzYWxUaW1lKCkuVG9TdHJpbmcoInl5eXktTU0tZGQgSEg6bW06c3MiKSB8IE91dC1GaWxlIC1GaWxlUGF0aCAiYzpcb3ZodXBkXHNjcmlwdFxjb3Vjb3UudHh0IiAtQXBwZW5kCg=="
  }
}

Même si le script de post-installation peut être envoyé à l'API en clair directement en échappant les bons caractères, il est recommandé d'envoyer à l'API le script encodé en base64 en utilisant par exemple la commande Powershell suivante :

[System.Convert]::ToBase64String((Get-Content -Path .\my-script.ps1 -Encoding Byte))

Voici le script PowerShell de post-installation en clair avec l'exemple ci-dessus :

"coucou postInstallationScriptPowerShell" | Out-File -FilePath "c:\ovhupd\script\coucou.txt"
(Get-ItemProperty -LiteralPath "Registry::HKLM\SOFTWARE\Microsoft\Cryptography" -Name "MachineGuid").MachineGuid | Out-File -FilePath "c:\ovhupd\script\coucou.txt" -Append
(Get-Date).ToUniversalTime().ToString("yyyy-MM-dd HH:mm:ss") | Out-File -FilePath "c:\ovhupd\script\coucou.txt" -Append

Comme vous pouvez le constater, le script PowerShell pour Windows est similaire à l'exemple ci-dessus de script bash pour Linux.

Lors de l'exécution du script de post-installation Windows, les fichiers suivants persistent :

• Le script lui-même : c:\ovhupd\script\custrun.ps1 (ou c:\ovhupd\script\custrun.cmd si script batch).
• Le fichier de logs du script: c:\ovhupd\script\customerscriptlog.txt.

Exemple de retour

{
    "taskId": 123456789,
    "status": "init",
    "startDate": "2024-01-26T17:57:10+01:00",
    "doneDate": null,
    "function": "reinstallServer",
    "comment": "Start bare metal OS installation"
}

123456789 correspond à l'identifiant de la tâche de réinstallation de l'OS. Vous pouvez suivre l'état d'avancement global de la tâche à l'aide de l'appel suivant :

Vous pouvez aussi avoir un état détaillé de chaque étape de la réinstallation grâce à l'appel suivant :

Changer le chemin du bootloader efi

Une valeur de bootloader efi est mise par défaut lorsque vous installez à partir d'un template OVHcloud, mais vous avez la possibilité de la modifier.

Vous pouvez récupérer le chemin par défaut à l'aide de cet appel :

Et vous pouvez le modifier grace à l'appel suivant :

Aller plus loin

Premiers pas avec un serveur dédié

Premiers pas avec un serveur dédié Kimsufi, So You Start ou Rise

Bring Your Own Image (BYOI)

Bring Your Own Linux (BYOLinux)

API OVHcloud et Stockage

Gestion du RAID logiciel

Gestion du RAID matériel

Échangez avec notre communauté d'utilisateurs.