API de configuration des VM

Guide complet pour modifier les configurations de VM dans VergeOS, y compris les mises à jour CPU/RAM, les notes, la gestion des disques et la gestion des interfaces réseau

Points clés

Modifier les paramètres de la VM comme le CPU, la RAM, la console et la vidéo via l’API REST
Gérer les disques avec des capacités de redimensionnement, d’ajout et de suppression
Mettre à jour les interfaces réseau et leurs configurations
Ajouter des notes de documentation aux VM pour le suivi opérationnel

Ce guide couvre la modification des configurations des machines virtuelles dans VergeOS après leur création, y compris les mises à jour CPU/RAM, la gestion des disques, les changements d’interface réseau et l’ajout de notes opérationnelles.

Étape: Configuration de la VM (3 sur 4) Entrée: clé VM (42) + clé machine (54), modifications de configuration Sortie: Paramètres de VM mis à jour, matériel modifié Précédent: VM sous tension → Gestion de l'alimentation de la VM Étapes suivantes courantes:

Opérations avancées → Opérations avancées de la VM
Cycle d’alimentation pour appliquer les changements → Gestion de l'alimentation de la VM

Ce document aide pour

"Comment changer le CPU et la RAM d’une VM"
"Ajout de disques de stockage aux VM existantes"
"Redimensionnement des disques et du stockage des VM"
"Gestion des interfaces réseau des VM"
"Ajout de notes et de documentation aux VM"
"Opérations à chaud et modifications en direct"
"Optimisation des performances de la VM"
"Flux de travail d’extension du stockage"
"Reconfiguration réseau"

Référence rapide

Endpoints principaux

Paramètres de la VM: PUT /api/v4/vms/{id}
Notes de la VM: POST /api/v4/note_actions
Gestion des disques: POST/PUT/DELETE /api/v4/machine_drives
Gestion des NIC: POST/PUT/DELETE /api/v4/machine_nics

Concepts clés

clé VM: À utiliser pour les paramètres de VM (CPU, RAM, console)
clé machine: À utiliser pour le matériel (disques, NIC, périphériques)
Branchement à chaud: Certains changements nécessitent un redémarrage de la VM

Authentification

-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"

Prérequis

La VM doit d'abord être créée → Voir Création de VM

Référence rapide de l'API

Opération

Méthode

Point de terminaison

Type de clé

Objectif

Mettre à jour la VM

PUT

/api/v4/vms/{id}

clé VM

Paramètres CPU, RAM, console

Ajouter une note

POST

/api/v4/note_actions

clé VM

Documentation

Ajouter un disque

POST

/api/v4/machine_drives

clé machine

Extension du stockage

Redimensionner le disque

PUT

/api/v4/machine_drives/{id}

Clé du disque

Augmenter la taille du disque

Supprimer le disque

DELETE

/api/v4/machine_drives/{id}

Clé du disque

Suppression du stockage

Ajouter une NIC

POST

/api/v4/machine_nics

clé machine

Interface réseau

Mettre à jour la NIC

PUT

/api/v4/machine_nics/{id}

Clé de la NIC

Modifications réseau

Supprimer la NIC

DELETE

/api/v4/machine_nics/{id}

Clé de la NIC

Suppression de l’interface

Index de dépannage

400 Mauvaise requête: Taille de RAM invalide, nombre de CPU invalide, JSON mal formé
409 Conflit: La VM doit être arrêtée, le hotplug n’est pas pris en charge, ressource en cours d’utilisation
507 Stockage insuffisant: Niveau plein, taille de disque trop grande, quota dépassé
403 Interdit: autorisations de la clé API, accès à la VM refusé, restrictions du cluster
422 Entité non traitable: Le disque ne peut pas être réduit, type d’interface invalide
404 Introuvable: VM introuvable, disque introuvable, NIC introuvable, vnet invalide

Mises à jour du CPU et de la RAM

PUT /api/v4/vms/{id}

Description: Met à jour la configuration de la VM. Utilise la clé VM (et non la clé machine) pour les paramètres au niveau de la VM.

Exemple du corps de la requête:

{
  "ram": 16384,
  "cpu_cores": 3,
  "console": "spice",
  "video": "qxl",
  "show_advanced": "true",
  "nested_virtualization": "true",
  "disable_hypervisor": "true"
}

Appel API complet:

curl -X PUT "https://your-vergeos.example.com/api/v4/vms/42" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "ram": 16384,
    "cpu_cores": 3,
    "console": "spice",
    "video": "qxl",
    "show_advanced": "true",
    "nested_virtualization": "true",
    "disable_hypervisor": "true"
  }'

Paramètres de configuration courants

Paramètre

Type

Description

Redémarrage requis

ram

entier

RAM en Mo

Généralement oui

cpu_cores

entier

Nombre de cœurs CPU

Généralement oui

console

chaîne

Type de console (spice, vnc, none)

Au prochain démarrage

video

chaîne

Adaptateur vidéo (qxl, virtio, std, cirrus)

Au prochain démarrage

nested_virtualization

chaîne

Activer la virtualisation imbriquée ("true"/"false")

Oui

disable_hypervisor

chaîne

Désactiver l’hyperviseur ("true"/"false")

Oui

guest_agent

chaîne

Activer l'agent invité ("true"/"false")

Au prochain démarrage

uefi

chaîne

Activer le démarrage UEFI ("true"/"false")

Oui

secure_boot

chaîne

Activer le démarrage sécurisé ("true"/"false")

Oui

Clé VM vs clé machine

Paramètres de la VM (CPU, RAM, console, vidéo) : utiliser la clé VM (par ex., 42) avec /api/v4/vms/{vm_key}
Modifications matérielles (disques, NIC, périphériques) : utiliser la clé machine (par ex., 54) avec /api/v4/machine_* points de terminaison

Modifications de configuration

Les changements de CPU et de RAM nécessitent généralement un redémarrage de la VM
Les changements de console et de vidéo prennent effet au prochain démarrage de la VM
Les paramètres de virtualisation imbriquée et d’hyperviseur nécessitent un redémarrage de la VM
Vérifiez toujours allow_hotplug paramètre pour les capacités d’ajout à chaud

Ajout de notes aux VM

POST /api/v4/note_actions

Description: Ajoute ou met à jour les notes d’une VM dans l’interface VergeOS à des fins de documentation.

Corps de la requête:

{
  "owner": "vms/42",
  "action": "update",
  "params": {
    "text": "Ceci est une VM de test"
  }
}

Appel API complet:

curl -X POST "https://your-vergeos.example.com/api/v4/note_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "owner": "vms/42",
    "action": "update",
    "params": {
      "text": "Serveur web de production - Mis à jour le 2025-08-24"
    }
  }'

Paramètres:

Nom

Type

Obligatoire

Description

owner

chaîne

Oui

Identifiant de ressource (format : "vms/{vm_key}")

action

chaîne

Oui

Action à effectuer ("update")

params.text

chaîne

Oui

Contenu du texte de la note

Notes de la VM

Les notes sont visibles dans l’interface VergeOS et aident à la documentation des VM, aux plannings de maintenance ou aux détails de configuration. Utilisez la clé VM (et non la clé machine) dans le champ owner.

Gestion des disques

Ajout de nouveaux disques

Utilisez le point de terminaison des disques machine pour ajouter du stockage après la création de la VM :

POST /api/v4/machine_drives

{
  "machine": "54",
  "name": "Disque de données",
  "interface": "virtio-scsi",
  "media": "disk",
  "disksize": 536870912000,
  "preferred_tier": "2"
}

Appel API complet:

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": "Disque de données",
    "interface": "virtio-scsi",
    "media": "disk",
    "disksize": 536870912000,
    "preferred_tier": "2"
  }'

Redimensionnement des disques

PUT /api/v4/machine_drives/{drive_id}

Description: Augmente la taille d’un disque existant. Notez que les disques peuvent seulement être agrandis, pas réduits.

{
  "disksize": 1073741824000
}

Appel API complet:

curl -X PUT "https://your-vergeos.example.com/api/v4/machine_drives/55" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "disksize": 1073741824000
  }'

Redimensionnement du disque

Les disques peuvent seulement être agrandis, jamais réduits
Le système d’exploitation invité peut devoir être configuré pour reconnaître la nouvelle taille
Certains systèmes de fichiers nécessitent une विस्तारion manuelle après le redimensionnement du disque

Suppression des disques

Avant la suppression, les disques doivent être désattachés à chaud si la VM est en cours d’exécution :

Étape 1 : désattacher le disque à chaud (si la VM est en cours d’exécution)

curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "vm": "42",
    "action": "hotplugdrive",
    "params": {
      "device": "drive-id-here",
      "unplug": true
    }
  }'

Étape 2 : supprimer le disque

DELETE /api/v4/machine_drives/{drive_id}

curl -X DELETE "https://your-vergeos.example.com/api/v4/machine_drives/55" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemples de gestion des disques

Ajout d’un CDROM/ISO

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

Ajout d’un disque d’importation

{
  "machine": "54",
  "name": "Ubuntu Server",
  "description": "Ubuntu 22.04 LTS",
  "interface": "virtio-scsi",
  "media": "import",
  "media_source": 123,
  "preferred_tier": "3"
}

Gestion des interfaces réseau

Ajout de NIC

POST /api/v4/machine_nics

{
  "machine": "54",
  "name": "Réseau secondaire",
  "interface": "virtio",
  "vnet": "8",
  "enabled": true
}

Appel API complet:

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",
    "name": "Réseau secondaire",
    "interface": "virtio",
    "vnet": "8",
    "enabled": true
  }'

Mise à jour de la configuration de la NIC

PUT /api/v4/machine_nics/{nic_id}

{
  "vnet": "10",
  "enabled": true
}

Appel API complet:

curl -X PUT "https://your-vergeos.example.com/api/v4/machine_nics/78" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "vnet": "10",
    "enabled": true
  }'

Suppression des NIC

DELETE /api/v4/machine_nics/{nic_id}

curl -X DELETE "https://your-vergeos.example.com/api/v4/machine_nics/78" \
  -H "Authorization: Bearer YOUR_API_KEY"

Paramètres de configuration de la NIC

Paramètre

Type

Obligatoire

Description

machine

chaîne

Oui

ID de machine

vnet

chaîne

Oui

ID du réseau virtuel

name

chaîne

Non

Nom de la NIC

interface

chaîne

Non

Type d’interface NIC (virtio, e1000, rtl8139)

enabled

booléen

Non

État d'activation de la NIC

Clés de réseau virtuel

Le vnet ce paramètre utilise la clé/l’ID du réseau. Vous pouvez trouver les clés de réseau en listant les réseaux disponibles via le point de terminaison de l’API des réseaux.

Flux de configuration complet

Voici un exemple de mise à jour de la configuration complète d’une VM :

# Étape 1 : mettre à jour les paramètres de la VM (CPU, RAM, console)
curl -X PUT "https://your-vergeos.example.com/api/v4/vms/42" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "ram": 32768,
    "cpu_cores": 8,
    "console": "spice",
    "video": "virtio"
  }'

# Étape 2 : ajouter une note opérationnelle
curl -X POST "https://your-vergeos.example.com/api/v4/note_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "owner": "vms/42",
    "action": "update",
    "params": {
      "text": "Passé à 32 Go de RAM et 8 cœurs pour augmenter la charge de travail - 2025-08-24"
    }
  }'

# Étape 3 : ajouter un stockage supplémentaire
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": "Données de l’application",
    "interface": "virtio-scsi",
    "media": "disk",
    "disksize": 1073741824000,
    "preferred_tier": "2"
  }'

# Étape 4 : ajouter une interface réseau secondaire
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",
    "name": "Réseau de gestion",
    "interface": "virtio",
    "vnet": "5",
    "enabled": true
  }'

Bonnes pratiques de configuration

Avant d’apporter des modifications

Vérifier l’état de la VM: S’assurer que la VM est dans un état approprié pour les modifications
Sauvegarder les données importantes: Créer des instantanés avant les changements majeurs
Examiner les dépendances: Prendre en compte l’impact sur les applications en cours d’exécution
Planifier une interruption: Certains changements nécessitent un redémarrage de la VM

Après avoir apporté des modifications

Vérifier la configuration: Vérifier que les changements ont été appliqués correctement
Tester le fonctionnement: S’assurer que la VM fonctionne comme prévu
Mettre à jour la documentation: Ajouter des notes sur les changements de configuration
Surveiller les performances: Surveiller tout impact sur les performances

Considérations sur le hotplug

# Vérifier si la VM prend en charge le hotplug
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=allow_hotplug" \
  -H "Authorization: Bearer YOUR_API_KEY"

Prise en charge du hotplug

Le allow_hotplug ce paramètre permet l’ajout et la suppression à chaud des disques et des NIC pendant que la VM est en cours d’exécution :

Lecteurs: Peut être ajouté/supprimé à la volée (le système d’exploitation invité doit le prendre en charge ; Virtio-SCSI recommandé)
Cartes réseau: Peut être ajouté/supprimé à la volée (largement pris en charge par les systèmes d’exploitation invités)
CPU/RAM: Les changements nécessitent toujours un cycle d’alimentation de la VM

Voir Capacités de hotplug de la VM pour plus de détails.

Gestion des erreurs

Erreurs de configuration courantes

Erreur: 400 Bad Request - Taille de RAM invalide

{
  "error": "La taille de la RAM doit être d’au moins 512 Mo et d’au plus 1048576 Mo"
}

Erreur: 409 Conflict - La VM doit être arrêtée

{
  "error": "Impossible de modifier les cœurs CPU pendant l’exécution de la VM sans prise en charge du hotplug"
}

Solution: Arrêtez la VM ou vérifiez les capacités de hotplug avant d’apporter des modifications.

Erreur: 507 Stockage insuffisant

{
  "error": "Espace de stockage insuffisant dans le niveau 2 pour la taille de disque demandée"
}

Solution: Choisissez un autre niveau de stockage ou réduisez la taille du disque.

Opérations associées

Création de VM: Voir Création de VM pour la configuration initiale de la VM
Gestion de l'alimentation: Voir Gestion de l'alimentation de la VM pour les opérations de démarrage/arrêt
Opérations avancées: Voir Opérations avancées de la VM pour le clonage et les instantanés

Besoin d’aide ?

Pour obtenir une सहायता supplémentaire avec la configuration de la 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

PrécédentAPI des opérations avancées sur les VM

SuivantAPI de création de VM

Mis à jour il y a 3 mois

Ce contenu vous a-t-il été utile ?