API des opérations avancées sur les VM

Guide complet des opérations avancées sur les VM dans VergeOS, y compris le clonage, les snapshots, la suppression et le dépannage

Points clés

• Cloner des VM avec configuration complète et copie des disques
• Créer et restaurer des instantanés de VM pour la sauvegarde et la reprise
• Supprimer les VM en toute sécurité avec nettoyage automatique des ressources
• Gestion complète des erreurs et conseils de dépannage

Ce guide couvre les opérations avancées des machines virtuelles dans VergeOS, notamment le clonage, la gestion des instantanés, la suppression et le dépannage. Ces opérations offrent de puissantes capacités pour la gestion du cycle de vie des VM et la reprise après sinistre.

Étape: Opérations avancées de VM (4 sur 4) Entrée: clé de VM (42), type d'opération, paramètres Sortie: VM clonées, instantanés, confirmation du nettoyage Précédent: VM configurée → Configuration de la VM Opérations courantes:

• Cloner pour les modèles → Cycle de création d'une nouvelle VM
• Instantané pour sauvegarde → Flux de reprise
• Supprimer pour le nettoyage → Fin du cycle de vie

Ce document aide pour

• "Comment cloner des VM via l'API"
• "Créer des instantanés et des sauvegardes de VM"
• "Restaurer des VM à partir d'instantanés"
• "Supprimer des VM et effectuer le nettoyage en toute sécurité"
• "Dépannage et diagnostics des VM"
• "Flux de création de modèles"
• "Opérations de reprise après sinistre"
• "Gestion groupée des VM"
• "Automatisation du nettoyage des ressources"

Référence rapide

Endpoints principaux

• Actions VM: POST /api/v4/vm_actions
• Suppression de VM: DELETE /api/v4/vms/{vm_key}
• Liste des VM: GET /api/v4/vms

Actions clés

• clonage: Créer une copie complète de la VM
• instantané: Créer un instantané de VM
• restaurer: Restaurer à partir d'un instantané

Authentification

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

Prérequis

La VM doit exister → Voir Création de VM

Référence rapide de l'API

Opération	Méthode	Point de terminaison	Type de clé	Objectif
Cloner la VM	POST	/api/v4/vm_actions	clé VM	Créer une copie complète
Créer un instantané	POST	/api/v4/vm_actions	clé VM	Sauvegarde à un instant donné
Restaurer un instantané	POST	/api/v4/vm_actions	clé VM	Opération de récupération
Lister les instantanés	GET	/api/v4/vms	Requête de filtrage	Trouver des instantanés
Supprimer la VM	DELETE	/api/v4/vms/{id}	clé VM	Suppression complète
État de la VM	GET	/api/v4/vms/{id}	clé VM	Vérification de la configuration
État de l'opération	GET	/api/v4/machine_status/{id}	clé machine	Surveillance à l'exécution

Index de dépannage

• 409 Conflit: le nom du clone existe, la VM est déjà en cours d'exécution, opération en cours
• 507 Stockage insuffisant: espace insuffisant pour le clone, stockage d'instantanés plein
• 403 Interdit: autorisations de la clé API, accès à la VM refusé, restrictions du cluster
• 404 Introuvable: VM introuvable, instantané introuvable, clé de VM invalide
• 408 Délai d'attente de la requête: délai d'attente de l'opération de clonage, délai d'attente de création de l'instantané
• 422 Entité non traitable: paramètres de clonage invalides, conflit lors de la restauration de l'instantané
• 500 Erreur interne du serveur: problèmes du système de stockage, problèmes de l'hyperviseur, défaillances du cluster

Clonage de VM

POST /api/v4/vm_actions

Description: Crée une copie complète d'une VM, y compris tous les disques et la configuration.

Clonage de base

{
  "params": {
    "name": "clone test",
    "quiesce": "true"
  },
  "action": "clone",
  "vm": "42"
}

Appel API complet:

curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "params": {
      "name": "clone test",
      "quiesce": "true"
    },
    "action": "clone",
    "vm": "42"
  }'

Exemple de réponse:

{
  "response": {
    "vmkey": "43",
    "machinekey": "55",
    "machinestatuskey": "55",
    "clusterkey": "1"
  }
}

Options avancées de clonage

{
  "params": {
    "name": "production-clone",
    "description": "Clone du serveur de production pour les tests",
    "preserve_macs": "true",
    "preserve_device_uuids": "true",
    "quiesce": "true",
    "cluster": "2"
  },
  "action": "clone",
  "vm": "42"
}

Paramètres du clone

Paramètre	Type	Obligatoire	Description
name	chaîne	Oui	Nom de la VM clonée
description	chaîne	Non	Description du clone
quiesce	chaîne	Non	Mettre la VM en pause avant le clonage ("true"/"false") pour assurer la cohérence des données
preserve_macs	chaîne	Non	Conserver les adresses MAC ("true"/"false")
preserve_device_uuids	chaîne	Non	Conserver les UUID des périphériques ("true"/"false")
cluster	chaîne	Non	ID du cluster cible

Options de clonage

• Mettre en pause: Utilisez "quiesce": "true" pour garantir la cohérence des données en mettant brièvement la VM en pause
• Conserver les MAC: Utilisez "preserve_macs": "true" pour conserver les mêmes adresses MAC (peut provoquer des conflits réseau)
• Conserver les UUID des périphériques: Utilisez "preserve_device_uuids": "true" pour conserver les identifiants des périphériques
• Inter-cluster: Indiquez un ID de cluster différent pour cloner vers un autre cluster

Exemple de flux de clonage

# Étape 1 : Créer le clone
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "params": {
      "name": "backup-clone-$(date +%Y%m%d)",
      "description": "Clone de sauvegarde automatisé",
      "quiesce": "true"
    },
    "action": "clone",
    "vm": "42"
  }'

# Étape 2 : Vérifier la création du clone (en utilisant le vmkey renvoyé)
curl "https://your-vergeos.example.com/api/v4/vms/43?fields=name,description,created" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Étape 3 : Vérifier l'état d'alimentation du clone
curl "https://your-vergeos.example.com/api/v4/machine_status/55?fields=powerstate,status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Instantanés de VM

Création d'instantanés

{
  "vm": "42",
  "action": "snapshot",
  "params": {
    "name": "instantané-avant-mise-à-jour",
    "description": "Avant la mise à jour du système"
  }
}

Appel API complet:

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": "snapshot",
    "params": {
      "name": "instantané-avant-mise-à-jour",
      "description": "Avant la mise à jour du système - $(date)"
    }
  }'

Restauration à partir d'instantanés

{
  "vm": "42",
  "action": "restore",
  "params": {
    "snapshot_id": "instantané-67890"
  }
}

Appel API complet:

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": "restore",
    "params": {
      "snapshot_id": "instantané-67890"
    }
  }'

Liste des instantanés de VM

GET /api/v4/vms

Utilisez des filtres pour trouver des instantanés :

curl "https://your-vergeos.example.com/api/v4/vms?filter=is_snapshot%20eq%20true%20and%20name%20contains%20'web-server'" \
  -H "Authorization: Bearer YOUR_API_KEY"

Trouver tous les instantanés d'une VM:

curl "https://your-vergeos.example.com/api/v4/vms?filter=is_snapshot%20eq%20true%20and%20parent_vm%20eq%2042" \
  -H "Authorization: Bearer YOUR_API_KEY"

Flux de gestion des instantanés

# Étape 1 : Créer un instantané avant la maintenance
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": "snapshot",
    "params": {
      "name": "instantané-maintenance-$(date +%Y%m%d-%H%M)",
      "description": "Instantané avant maintenance"
    }
  }'

# Étape 2 : Lister les instantanés pour trouver l'ID de l'instantané
curl "https://your-vergeos.example.com/api/v4/vms?filter=is_snapshot%20eq%20true%20and%20parent_vm%20eq%2042&fields=name,description,created" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Étape 3 : Restaurer si nécessaire (après des problèmes de maintenance)
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": "restore",
    "params": {
      "snapshot_id": "id-d'instantané-trouvé"
    }
  }'

Suppression et nettoyage de VM

Suppression complète de la VM

DELETE /api/v4/vms/{vm_key}

Description: Supprime une VM et élimine automatiquement toutes les ressources associées, y compris les disques, les NIC, les périphériques et les configurations.

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

Réponse: 200 OK en cas de suppression réussie.

Nettoyage automatique

Lorsque vous supprimez une VM à l'aide de DELETE /api/v4/vms/{vm_key}, VergeOS supprime automatiquement :

• Tous les disques attachés à la VM
• Toutes les interfaces réseau (NIC)
• Tous les périphériques (GPU, passthrough PCI, USB, TPM, etc.)
• Configuration de la VM et métadonnées
• Fichiers cloud-init et configurations
• Notes de la VM et documentation
• Ressources machine associées

Considérations avant suppression

Avant de supprimer une VM, prenez en compte :

1. Sauvegarde des données: Assurez-vous que les données importantes sont sauvegardées
2. Instantanés: les instantanés de VM peuvent être supprimés avec la VM
3. Dépendances: Vérifiez si d'autres systèmes dépendent de cette VM
4. Configuration réseau: Notez toute configuration réseau particulière
5. Licences: Tenez compte des implications liées aux licences logicielles

Processus de suppression sécurisée

Étape 1 : Éteindre la VM (recommandé)

curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "action": "kill",
    "vm": "42"
  }'

Étape 2 : Vérifier l'état d'alimentation

curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate" \
  -H "Authorization: Bearer YOUR_API_KEY"

Étape 3 : Créer une sauvegarde finale (facultatif)

curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "params": {
      "name": "sauvegarde-finale-avant-suppression",
      "description": "Sauvegarde finale avant la suppression de la VM"
    },
    "action": "clone",
    "vm": "42"
  }'

Étape 4 : Supprimer la VM et toutes les ressources

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

Utilisation de la clé VM

Utilisez la clé VM (par exemple, 42) à partir de la réponse de création de la VM ou de la liste des VM, et non la clé machine. Le processus de suppression gère automatiquement toutes les ressources machine associées.

Aucun nettoyage manuel requis

Contrairement à certaines plateformes de virtualisation, VergeOS gère automatiquement le nettoyage complet des ressources. Vous n'avez pas pas besoin de procéder manuellement à :

• Supprimer des disques individuels
• Retirer les interfaces réseau
• Détacher les périphériques
• Nettoyer les fichiers de configuration
• Supprimer les entrées d'état de la machine

La seule DELETE /api/v4/vms/{vm_key} opération gère automatiquement tout le nettoyage.

Recherche de ressources orphelines

# Trouver les disques sans machines associées
curl "https://your-vergeos.example.com/api/v4/machine_drives?filter=machine%20eq%20null" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Trouver les NIC sans machines associées
curl "https://your-vergeos.example.com/api/v4/machine_nics?filter=machine%20eq%20null" \
  -H "Authorization: Bearer YOUR_API_KEY"

Gestion des erreurs et dépannage

Scénarios d'erreur courants

Échecs de création de VM

Erreur: 400 Requête incorrecte - type de machine invalide

{
  "error": "Type de machine invalide 'invalid-type'. Options valides : pc, q35, pc-i440fx-*, pc-q35-*"
}

Solution: Utilisez des types de machines valides issus de la liste prise en charge.

Conflits d'état d'alimentation

Erreur: 409 Conflit - la VM est déjà en cours d'exécution

{
  "error": "Impossible de mettre la VM sous tension : elle est déjà à l'état en cours d'exécution"
}

Solution: Vérifiez l'état d'alimentation actuel avant d'envoyer des commandes d'alimentation.

Contraintes de ressources

Erreur: 507 Stockage insuffisant

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

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

Échecs de clonage

Erreur: 409 Conflit - le nom du clone existe déjà

{
  "error": "La VM nommée 'clone test' existe déjà"
}

Solution: Utilisez des noms uniques pour les VM clonées.

Surveillance des opérations de VM

Vérification de l'état de l'opération

De nombreuses opérations de VM sont asynchrones. Surveillez la progression à l'aide de :

# Vérifier l'état de la VM
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=machine%23status" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Vérifier l'état de la machine pour les informations d'exécution
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=status,powerstate" \
  -H "Authorization: Bearer YOUR_API_KEY"

Délais d'attente des opérations

Définissez des délais d'attente appropriés pour les opérations longues :

• Création de VM: 5 à 10 minutes
• Opérations de clonage: 10 à 30 minutes (selon la taille)
• Création d'instantané: 2 à 5 minutes
• Restauration d'instantané: 5 à 15 minutes
• Changements d'état d'alimentation: 30 à 60 secondes
• Suppression de VM: 2 à 5 minutes

Logique de relance

Implémentez une logique de relance pour les échecs transitoires :

import time
import requests

def wait_for_operation_completion(vm_id, max_retries=20):
    """Attendre la fin de l'opération de VM"""
    for attempt in range(max_retries):
        response = requests.get(
            f"https://your-vergeos.example.com/api/v4/vms/{vm_id}",
            params={"fields": "machine#status#status as operation_status"},
            headers={"Authorization": "Bearer YOUR_API_KEY"}
        )
        
        status = response.json().get("operation_status", "")
        if status not in ["cloning", "snapshotting", "restoring"]:
            return True
            
        time.sleep(10)  # Attendre 10 secondes entre les vérifications
    
    return False

# Exemple d'utilisation
if wait_for_operation_completion("42"):
    print("Opération terminée avec succès")
else:
    print("Délai d'attente de l'opération dépassé")

Débogage des problèmes de VM

Vérifier la configuration de la VM

# Obtenir la configuration complète de la VM
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=most" \
  -H "Authorization: Bearer YOUR_API_KEY"

Vérifier l'état de la machine

# Obtenir l'état d'exécution et les erreurs
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=most" \
  -H "Authorization: Bearer YOUR_API_KEY"

Vérifier les ressources système

# Vérifier les ressources du cluster
curl "https://your-vergeos.example.com/api/v4/clusters/1?fields=resources" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Vérifier les niveaux de stockage
curl "https://your-vergeos.example.com/api/v4/storage_tiers" \
  -H "Authorization: Bearer YOUR_API_KEY"

Bonnes pratiques

1. Testez toujours les opérations dans les environnements de développement d'abord
2. Créez des instantanés avant les changements majeurs
3. Surveillez l'utilisation des ressources pendant les opérations
4. Implémentez une gestion des erreurs appropriée dans les scripts d'automatisation
5. Utilisez des noms descriptifs pour les clones et les instantanés
6. Nettoyez régulièrement les ressources inutilisées
7. Documentez les procédures opérationnelles pour votre équipe

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
• Configuration: Voir Configuration de la VM pour les modifications du CPU/RAM

Besoin d’aide ?

Pour une assistance supplémentaire sur les opérations avancées des 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