> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/knowledge-base/fr/automation-api/vm-creation-api.md). # API de création de VM {% hint style="info" %} **Points clés** * Créez des VM avec les paramètres de configuration essentiels à l'aide de l'API REST * Prise en charge de la création de VM basée sur des recettes avec des configurations complexes * Ajoutez des disques, des périphériques et des interfaces réseau après la création de la VM * Comprendre les distinctions entre la clé VM et la clé machine selon les opérations {% endhint %} Ce guide couvre la création de machines virtuelles dans VergeOS, depuis la création de VM de base jusqu'à l'ajout de disques, de périphériques et d'interfaces réseau. L'API VergeOS fournit des points de terminaison complets pour la création de VM et la configuration matérielle. **Étape**: Création de VM (1 sur 4) **Entrée**: identifiants API, informations du cluster, spécifications de la VM **Sortie**: clé VM (42) + clé machine (54) **Suivant**: Utilisez les clés pour la gestion de l'alimentation **Étapes suivantes courantes**: * Mise sous tension de la VM → [`Gestion de l'alimentation de la VM`](/knowledge-base/fr/automation-api/vm-power-management.md) * Configurer les paramètres → [`Configuration de la VM`](/knowledge-base/fr/automation-api/vm-configuration.md) * Opérations avancées → [`Opérations avancées de la VM`](/knowledge-base/fr/automation-api/vm-advanced-operations.md) ## Ce document aide pour * "Comment créer une VM via l'API" * "Ajouter des disques lors de la configuration de la VM" * "Attacher des périphériques GPU/PCI aux VM" * "Création de VM avec cloud-init" * "Comprendre les clés VM vs machine" * "Configurer des interfaces réseau pour de nouvelles VM" * "Provisionnement de VM basé sur des recettes" * "Automatisation de la création en masse de VM" * "Déploiement de VM en infrastructure as code" ## Référence rapide ### Endpoints principaux * **Créer la VM**: `POST /api/v4/vms` * **Ajouter un disque**: `POST /api/v4/machine_drives` * **Ajouter un périphérique**: `POST /api/v4/machine_devices` * **Ajouter une NIC**: `POST /api/v4/machine_nics` ### Paramètres clés * `name`: identifiant de VM (obligatoire) * `cluster`: ID du cluster cible * `machine`: ID de machine issu de la création de VM (pour l'ajout de matériel) * `resource_group`: UUID pour le passage de périphérique ### Authentification ```bash -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" ``` ### Étapes suivantes Après la création de la VM → Gestion de l'alimentation ([`Gestion de l'alimentation de la VM`](/knowledge-base/fr/automation-api/vm-power-management.md)) ## Référence rapide de l'API | Opération | Méthode | Point de terminaison | Type de clé | Objectif | | ----------------------- | ------- | ----------------------------- | ---------------- | ----------------- | | Créer la VM | POST | `/api/v4/vms` | Renvoie les deux | Création initiale | | Ajouter un disque | POST | `/api/v4/machine_drives` | clé machine | Matériel | | Ajouter un périphérique | POST | `/api/v4/machine_devices` | clé machine | Passage GPU/PCI | | Ajouter une NIC | POST | `/api/v4/machine_nics` | clé machine | Interface réseau | | Mise sous tension | POST | `/api/v4/vm_actions` | clé VM | Contrôle | | Vérifier l'état | GET | `/api/v4/machine_status/{id}` | clé machine | Surveiller | ## Index de dépannage * **409 Conflit**: Le nom de la VM existe déjà, déjà en cours d'exécution, autorisation refusée * **400 Mauvaise requête**: Paramètres invalides, champs obligatoires manquants, JSON invalide * **507 Stockage insuffisant**: Niveau plein, réduisez la taille, choisissez un autre niveau * **403 Interdit**: Permissions de la clé API, accès au cluster refusé * **404 Introuvable**: ID de cluster invalide, source de média manquante, groupe de ressources invalide * **422 Entité non traitable**: Interface de disque invalide, type de média non pris en charge ## Prérequis * Identifiants API VergeOS valides avec des permissions de gestion des VM * Compréhension des concepts VergeOS : clusters, vnets, sources de média et groupes de ressources * Connaissances de base des principes de l'API REST et du formatage JSON ## Authentification Toutes les opérations de création de VM nécessitent une authentification via : * **Clé API**: Inclure dans le `Authorization` en-tête sous forme de `Bearer YOUR_API_KEY` * **Authentification de base**: Nom d'utilisateur et mot de passe pour les sessions interactives * **Jeton de session**: Pour les intégrations web ```bash # Utilisation de la clé API curl -H "Authorization: Bearer YOUR_API_KEY" \\ -H "Content-Type: application/json" \\ https://your-vergeos.example.com/api/v4/vms ``` ## Création de VM basique ### POST /api/v4/vms **Description**: Crée une nouvelle machine virtuelle avec la configuration spécifiée. **Paramètres de requête**: | Nom | Type | Obligatoire | Description | | ------------------- | ------ | ----------- | --------------------------------------------------------------- | | name | chaîne | Oui | Nom de VM unique | | description | chaîne | Non | Description de la VM | | cluster | chaîne | Non | ID du cluster cible (chaîne numérique) | | ram | entier | Non | RAM en Mo (par défaut : 1024) | | cpu\_cores | entier | Non | Nombre de cœurs CPU (par défaut : 1) | | guest\_agent | chaîne | Non | Activer l'agent invité ("true"/"false") | | console\_pass\_hash | chaîne | Non | Hash du mot de passe de la console (chaîne vide si non utilisé) | | video | chaîne | Non | Type d'adaptateur vidéo (virtio, std, cirrus, etc.) | | rtc\_base | chaîne | Non | Paramètre de base RTC (utc, heure locale) | | uefi | chaîne | Non | Activer le démarrage UEFI ("true"/"false") | **Exemple du corps de la requête**: ```json { "name": "web-server-01", "description": "Serveur web de production", "cluster": "1", "ram": 8192, "cpu_cores": 4, "guest_agent": "true", "console_pass_hash": "", "video": "virtio", "rtc_base": "utc", "uefi": "true" } ``` **Exemple de réponse**: ```json { "location": "/v4/vms/42", "dbpath": "vms/42", "$row": 42, "$key": "42", "response": { "machine": "54" } } ``` **Champs de réponse**: | Champ | Type | Description | | ---------------- | ------ | ---------------------------------------------------------------------- | | location | chaîne | Point de terminaison API de la VM créée | | dbpath | chaîne | Chemin de base de données de l'enregistrement de la VM | | $row | entier | Numéro de ligne de base de données | | $key | chaîne | ID de VM (utilisé pour les appels API suivants) | | response.machine | chaîne | ID de machine (utilisé pour les disques, les NIC et les périphériques) | **Réponses d'erreur**: * `400 Mauvaise requête`: Paramètres de configuration invalides * `409 Conflit`: Le nom de la VM existe déjà * `403 Interdit`: Autorisations insuffisantes {% hint style="success" %} **Clé VM vs clé machine** * **clé VM** (par ex., "42") : à utiliser pour les paramètres de VM comme le CPU, la RAM, la console * **clé machine** (par ex., "54") : à utiliser pour le matériel comme les disques, les NIC et les périphériques * Vous obtenez les deux clés dans la réponse de création de VM {% endhint %} ## Création de VM basée sur des recettes VergeOS prend en charge la création complexe de VM à l'aide de recettes qui incluent des disques, des interfaces réseau et des périphériques. ### VM complète avec configuration de recette ```json { "name": "enterprise-vm", "description": "Serveur d'applications d'entreprise", "cluster": "1", "cpu_cores": 8, "ram": 16384, "guest_agent": "true", "video": "virtio", "rtc_base": "utc", "uefi": "true", "secure_boot": "true", "console_pass_hash": "", "cloudinit_datasource": "nocloud", "cloudinit_files": [ { "name": "user-data", "contents": "#cloud-config\nusers:\n - name: admin\n sudo: ALL=(ALL) NOPASSWD:ALL\n ssh_authorized_keys:\n - ssh-rsa AAAAB3NzaC1yc2E..." }, { "name": "meta-data", "contents": "instance-id: enterprise-vm-001\nlocal-hostname: enterprise-vm" } ] } ``` ## Ajout de disques Les disques doivent être créés séparément après la création de la VM à l'aide du point de terminaison des disques machine. ### POST /api/v4/machine\_drives **Paramètres de requête**: | Nom | Type | Obligatoire | Description | | --------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------- | | machine | chaîne | Oui | ID de machine issu de la création de VM | | name | chaîne | Non | Nom du disque | | media | chaîne | Non | Type de média (disk, cdrom, import, clone, efidisk) | | interface | chaîne | Non | Interface du disque (virtio-scsi, ide, ahci, etc.) | | disksize | entier | Non | Taille du disque en octets (pour les nouveaux disques) | | preferred\_tier | chaîne | Non | Niveau de stockage (1-5) | | media\_source | chaîne | Non | ID du média source (pour import/clone/cdrom) | | show\_pt | chaîne | Non | Remplacer le niveau préféré ("true"/"false") - remplace le niveau par défaut de la source de média | ### Création d'un disque de démarrage ```json { "machine": "54", "name": "OS Drive", "media": "disk", "interface": "virtio-scsi", "disksize": 2199023255552, "preferred_tier": "1" } ``` **Exemple de réponse**: ```json { "location": "/v4/machine_drives/54", "dbpath": "machine_drives/54", "$row": 54, "$key": "54" } ``` ### Ajout d'un CD-ROM/ISO ```json { "machine": "54", "media": "cdrom", "interface": "ahci", "media_source": "7" } ``` **Exemple de réponse**: ```json { "location": "/v4/machine_drives/55", "dbpath": "machine_drives/55", "$row": 55, "$key": "55" } ``` ### Importation depuis une source de média ```json { "machine": "54", "name": "Ubuntu Server", "description": "Ubuntu 22.04 LTS", "interface": "virtio-scsi", "media": "import", "media_source": 123, "preferred_tier": "3" } ``` ## Ajout de périphériques (GPU, passage PCI, etc.) ### POST /api/v4/machine\_devices **Description**: Attache des périphériques matériels comme des GPU, des périphériques PCI, des périphériques USB ou un TPM à une machine virtuelle. **Paramètres de requête**: | Nom | Type | Obligatoire | Description | | --------------- | ------ | ----------- | --------------------------------------------------------------------------- | | machine | chaîne | Oui | ID de machine | | resource\_group | chaîne | Oui | UUID du groupe de ressources pour le périphérique | | settings\_args | objet | Non | Paramètres spécifiques au périphérique (objet vide pour le passage de base) | ### GPU en passage PCI ```json { "machine": "54", "resource_group": "1f67f07e-f653-db95-c475-01b8a2ea0ff1", "settings_args": {} } ``` **Exemple de réponse**: ```json { "location": "/v4/machine_devices/2", "dbpath": "machine_devices/2", "$row": 2, "$key": "2", "response": { "uuid": "934e250b-a13c-bd8f-104d-a31995b06eba" } } ``` {% hint style="success" %} **Recherche des groupes de ressources** Le `resource_group` paramètre identifie le périphérique matériel spécifique à attacher. Utilisez ces points de terminaison pour trouver les UUID des groupes de ressources disponibles : * `GET /api/v4/resource_groups` - Périphériques matériels généraux (GPU, périphériques PCI, USB, etc.) * `GET /api/v4/node_nvidia_vgpu_devices` - Périphériques NVIDIA vGPU spécifiquement {% endhint %} ### Recherche des périphériques disponibles ```bash # Périphériques matériels généraux curl "https://your-vergeos.example.com/api/v4/resource_groups" \\ -H "Authorization: Bearer YOUR_API_KEY" # Périphériques NVIDIA vGPU curl "https://your-vergeos.example.com/api/v4/node_nvidia_vgpu_devices" \\ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Ajout d'interfaces réseau ### POST /api/v4/machine\_nics **Paramètres de requête**: | Nom | Type | Obligatoire | Description | | --------- | ------- | ----------- | ------------------------------------------ | | machine | chaîne | Oui | ID de machine | | vnet | chaîne | Oui | ID du réseau virtuel (clé du réseau cible) | | name | chaîne | Non | Nom de la NIC | | interface | chaîne | Non | Type d'interface NIC (virtio, e1000, etc.) | | enabled | booléen | Non | État d'activation de la NIC | **Exemple**: ```json { "machine": "54", "vnet": "3" } ``` **Exemple de réponse**: ```json { "location": "/v4/machine_nics/78", "dbpath": "machine_nics/78", "$row": 78, "$key": "78" } ``` {% hint style="info" %} **Clés de réseau virtuel** Le `vnet` Le paramètre utilise la clé/l'ID du réseau. Par exemple, vnet "3" pourrait être votre réseau externe. Vous pouvez trouver les clés réseau en listant les réseaux disponibles via le point de terminaison API des réseaux. {% endhint %} ## Exemple complet de création de VM Voici un flux de travail complet pour créer une VM avec des disques, des périphériques et des interfaces réseau : ```bash # Étape 1 : Créer la VM curl -X POST "https://your-vergeos.example.com/api/v4/vms" \\ -H "Authorization: Bearer YOUR_API_KEY" \\ -H "Content-Type: application/json" \\ -d '{ "name": "production-server", "description": "Serveur d'applications de production", "cluster": "1", "ram": 16384, "cpu_cores": 8, "guest_agent": "true", "video": "virtio", "uefi": "true" }' # Réponse : clé VM = 42, clé machine = 54 # Étape 2 : Ajouter le disque de démarrage curl -X POST "https://your-vergeos.example.com/api/v4/machine_drives" \\ -H "Authorization: Bearer YOUR_API_KEY" \\ -H "Content-Type: application/json" \\ -d '{ "machine": "54", "name": "Boot Drive", "media": "disk", "interface": "virtio-scsi", "disksize": 107374182400, "preferred_tier": "1" }' # Étape 3 : Ajouter une interface réseau curl -X POST "https://your-vergeos.example.com/api/v4/machine_nics" \\ -H "Authorization: Bearer YOUR_API_KEY" \\ -H "Content-Type: application/json" \\ -d '{ "machine": "54", "vnet": "3" }' # Étape 4 : Ajouter un GPU (facultatif) curl -X POST "https://your-vergeos.example.com/api/v4/machine_devices" \\ -H "Authorization: Bearer YOUR_API_KEY" \\ -H "Content-Type: application/json" \\ -d '{ "machine": "54", "resource_group": "1f67f07e-f653-db95-c475-01b8a2ea0ff1", "settings_args": {} }' ``` {% hint style="info" %} **Opérations associées** * **Gestion de l'alimentation**: Voir [`Gestion de l'alimentation de la VM`](/knowledge-base/fr/automation-api/vm-power-management.md) pour démarrer/arrêter des VM * **Configuration**: Voir [`Configuration de la VM`](/knowledge-base/fr/automation-api/vm-configuration.md) pour les modifications du CPU/RAM * **Opérations avancées**: Voir [`Opérations avancées de la VM`](/knowledge-base/fr/automation-api/vm-advanced-operations.md) pour le clonage et les instantanés {% endhint %} {% hint style="info" %} **Besoin d’aide ?** Pour une assistance supplémentaire concernant la création de VM : * Consultez le portail de documentation VergeOS * Contactez le support VergeOS avec des messages d'erreur spécifiques * Consultez les journaux système pour obtenir des informations détaillées sur l'erreur * Consultez les forums communautaires VergeOS {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.verge.io/knowledge-base/fr/automation-api/vm-creation-api.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.