> 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-advanced-operations.md).

# API des opérations avancées de VM

{% hint style="info" %}
**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
  {% endhint %}

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`](/knowledge-base/fr/automation-api/vm-configuration.md) **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

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

### Prérequis

La VM doit exister → Voir [`Création de VM`](/knowledge-base/fr/automation-api/vm-creation-api.md)

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

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

**Appel API complet**:

```bash
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**:

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

### Options avancées de clonage

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

{% hint style="success" %}
**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
  {% endhint %}

### Exemple de flux de clonage

```bash
# É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

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

**Appel API complet**:

```bash
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

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

**Appel API complet**:

```bash
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 :

```bash
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**:

```bash
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

```bash
# É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.

```bash
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.

{% hint style="success" %}
**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**
  {% endhint %}

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

```bash
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

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

```bash
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

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

{% hint style="success" %}
**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.
{% endhint %}

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

```bash
# 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`

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

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

```json
{
  "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à`

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

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

```python
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

```bash
# 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

```bash
# 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

```bash
# 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

{% hint style="info" %}
**Opérations associées**

* **Création de VM**: Voir [`Création de VM`](/knowledge-base/fr/automation-api/vm-creation-api.md) pour la configuration initiale de la VM
* **Gestion de l'alimentation**: Voir [`Gestion de l'alimentation de la VM`](/knowledge-base/fr/automation-api/vm-power-management.md) pour les opérations de démarrage/arrêt
* **Configuration**: Voir [`Configuration de la VM`](/knowledge-base/fr/automation-api/vm-configuration.md) pour les modifications du CPU/RAM
  {% endhint %}

{% hint style="info" %}
**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
  {% 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-advanced-operations.md?ask=<question>&goal=<endgoal>
```

`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.