API de création de VM

Guide complet pour créer des machines virtuelles dans VergeOS, y compris la création de base, les configurations basées sur des recettes, les disques, les périphériques et les interfaces réseau

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

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
• Configurer les paramètres → Configuration de la VM
• Opérations avancées → Opérations avancées de la VM

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

-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)

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

# 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:

{
  "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:

{
  "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

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

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

{
  "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

{
  "machine": "54",
  "name": "OS Drive",
  "media": "disk",
  "interface": "virtio-scsi",
  "disksize": 2199023255552,
  "preferred_tier": "1"
}

Exemple de réponse:

{
  "location": "/v4/machine_drives/54",
  "dbpath": "machine_drives/54",
  "$row": 54,
  "$key": "54"
}

Ajout d'un CD-ROM/ISO

{
  "machine": "54",
  "media": "cdrom",
  "interface": "ahci",
  "media_source": "7"
}

Exemple de réponse:

{
  "location": "/v4/machine_drives/55",
  "dbpath": "machine_drives/55",
  "$row": 55,
  "$key": "55"
}

Importation depuis une source de média

{
  "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

{
  "machine": "54",
  "resource_group": "1f67f07e-f653-db95-c475-01b8a2ea0ff1",
  "settings_args": {}
}

Exemple de réponse:

{
  "location": "/v4/machine_devices/2",
  "dbpath": "machine_devices/2",
  "$row": 2,
  "$key": "2",
  "response": {
    "uuid": "934e250b-a13c-bd8f-104d-a31995b06eba"
  }
}

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

Recherche des périphériques disponibles

# 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:

{
  "machine": "54",
  "vnet": "3"
}

Exemple de réponse:

{
  "location": "/v4/machine_nics/78",
  "dbpath": "machine_nics/78",
  "$row": 78,
  "$key": "78"
}

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.

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 :

# É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": {}
  }'

Opérations associées

• Gestion de l'alimentation: Voir Gestion de l'alimentation de la VM pour démarrer/arrêter des VM
• Configuration: Voir Configuration de la VM pour les modifications du CPU/RAM
• Opérations avancées: Voir Opérations avancées de la VM pour le clonage et les instantanés

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