> 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-power-management.md).

# API de gestion de l’alimentation des VM

{% hint style="info" %}
**Points clés**

* Contrôlez les états d'alimentation des VM via des points de terminaison REST API
* Prise en charge des opérations d'alimentation gracieuses et forcées
* Surveillez l'état d'alimentation et le statut d'exécution de la VM
* Comprenez la clé VM par rapport à la clé Machine pour différents contrôles d'état
  {% endhint %}

Ce guide couvre la gestion des états d'alimentation des machines virtuelles dans VergeOS, notamment le démarrage, l'arrêt, le redémarrage et la surveillance des VM. L'API VergeOS fournit des capacités complètes de gestion de l'alimentation avec des opérations à la fois gracieuses et forcées.

**Étape**: Gestion de l'alimentation des VM (2 sur 4) **Entrée**: Clé VM (42) depuis la création, type d'opération d'alimentation **Sortie**: Modifications de l'état d'alimentation, statut d'exécution **Précédent**: VM créée → [`Création de VM`](/knowledge-base/fr/automation-api/vm-creation-api.md) **Étapes suivantes courantes**:

* Configurer les paramètres de la VM → [`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 démarrer/arrêter des VM via l'API"
* "Vérification de l'état d'alimentation de la VM"
* "Arrêt gracieux vs arrêt forcé de la VM"
* "Opérations de redémarrage et de réinitialisation de la VM"
* "Surveillance de l'état d'alimentation de la VM"
* "Automatisation de la gestion de l'alimentation"
* "Dépannage du démarrage de la VM"
* "Opérations d'alimentation planifiées"
* "Optimisation des ressources grâce au contrôle de l'alimentation"

## Référence rapide

### Endpoints principaux

* **Actions d'alimentation**: `POST /api/v4/vm_actions`
* **État de la VM**: `GET /api/v4/vms/{id}`
* **État d’alimentation**: `GET /api/v4/machine_status/{machine_id}`

### Actions clés

* `poweron`: Démarrer la VM
* `poweroff`: Arrêt gracieux (ACPI)
* `kill`: Forcer l'arrêt
* `reset`: Redémarrer la VM

### Authentification

```bash
-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`](/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                      |
| ------------------- | ------- | ----------------------------- | ----------- | ----------------------------- |
| Mise sous tension   | POST    | `/api/v4/vm_actions`          | clé VM      | Démarrer la machine virtuelle |
| Mettre hors tension | POST    | `/api/v4/vm_actions`          | clé VM      | Arrêt gracieux (ACPI)         |
| Forcer l'arrêt      | POST    | `/api/v4/vm_actions`          | clé VM      | Arrêt immédiat                |
| Redémarrez          | POST    | `/api/v4/vm_actions`          | clé VM      | Redémarrer la VM              |
| Informations VM     | GET     | `/api/v4/vms/{id}`            | clé VM      | Données de configuration      |
| État d’alimentation | GET     | `/api/v4/machine_status/{id}` | clé machine | Statut d'exécution            |

## Index de dépannage

* **409 Conflit**: VM déjà en cours d'exécution, VM non en cours d'exécution, incohérence de l'état d'alimentation
* **507 Ressources insuffisantes**: Ressources de cluster insuffisantes, mémoire/CPU indisponible
* **403 Interdit**: Permissions de la clé API, accès au cluster refusé, accès à la VM restreint
* **404 Introuvable**: Clé VM invalide, VM supprimée, clé machine introuvable
* **408 Délai d'attente de la requête**: Délai d'attente de l'opération d'alimentation dépassé, VM ne répond pas, échec de communication avec le cluster
* **500 Erreur interne du serveur**: Problèmes d'hyperviseur, problèmes de nœud, défaillances de stockage

## Démarrage des VM

### POST /api/v4/vm\_actions

**Description**: Met sous tension une machine virtuelle et attend qu'elle atteigne l'état d'exécution.

**Requête de mise sous tension**:

```json
{
  "action": "poweron",
  "params": {},
  "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 '{
    "action": "poweron",
    "params": {},
    "vm": "42"
  }'
```

**Réponse**: `201 Créé` lorsque l'action est lancée.

{% hint style="success" %}
**Bonnes pratiques**

* Vérifiez toujours la configuration de la VM avant la mise sous tension
* Assurez-vous que tous les lecteurs et interfaces réseau requis sont connectés
* Vérifiez la disponibilité des ressources du cluster
* Vérifiez que la VM n'est pas déjà en cours d'exécution pour éviter les conflits
  {% endhint %}

## Arrêt des VM

### Arrêt gracieux (ACPI)

**Description**: Envoie un signal d'arrêt ACPI au système d'exploitation invité, lui permettant de s'arrêter proprement.

```json
{
  "action": "poweroff",
  "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 '{
    "action": "poweroff",
    "vm": "42"
  }'
```

### Arrêt forcé (Kill)

**Description**: Termine immédiatement la VM sans permettre au système d'exploitation invité de s'arrêter proprement. À utiliser uniquement lorsque l'arrêt gracieux échoue.

```json
{
  "action": "kill",
  "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 '{
    "action": "kill",
    "vm": "42"
  }'
```

{% hint style="warning" %}
**Forcer l'arrêt**

Utiliser `kill` l'action peut entraîner une perte ou une corruption de données. Essayez toujours d'abord un arrêt gracieux `poweroff` en premier et n'utilisez `kill` que lorsque c'est nécessaire.
{% endhint %}

## Redémarrage des VM

### Redémarrage gracieux (ACPI)

**Description**: Envoie un signal de réinitialisation ACPI au système d'exploitation invité pour un redémarrage propre.

```json
{
  "action": "reset",
  "params": {
    "graceful": true
  },
  "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 '{
    "action": "reset",
    "params": {
      "graceful": true
    },
    "vm": "42"
  }'
```

### Réinitialisation matérielle (cycle d'alimentation)

**Description**: Redémarre immédiatement la VM sans permettre au système d'exploitation invité de s'arrêter proprement.

```json
{
  "action": "reset",
  "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 '{
    "action": "reset",
    "vm": "42"
  }'
```

## État et informations de la VM

### GET /api/v4/vms/{id}

**Description**: Récupère la configuration et les métadonnées de la VM à l'aide de divers filtres de champs.

**Obtenir toutes les informations de la VM**:

```bash
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=most" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Exemple de réponse**:

```json
{
  "$key": 42,
  "name": "test",
  "machine": 54,
  "description": "vm de test",
  "enabled": true,
  "created": 1755991665,
  "modified": 1755993248,
  "is_snapshot": false,
  "machine_type": "pc-q35-9.0",
  "allow_hotplug": true,
  "guest_agent": true,
  "cpu_cores": 3,
  "cpu_type": "host",
  "ram": 16384,
  "console": "spice",
  "video": "qxl",
  "sound": "none",
  "os_family": "linux",
  "rtc_base": "utc",
  "boot_order": "cd",
  "console_pass_enabled": false,
  "usb_tablet": true,
  "uefi": true,
  "secure_boot": false,
  "serial_port": false,
  "boot_delay": 5,
  "uuid": "821e96ec-2479-7cc4-7c14-c623557bdd2b",
  "need_restart": false,
  "console_status": 42,
  "cloudinit_datasource": "none",
  "imported": false,
  "created_from": "custom",
  "migration_method": "auto",
  "note": "Ceci est une VM de test",
  "power_cycle_timeout": 0,
  "allow_export": true,
  "creator": "admin",
  "nested_virtualization": true,
  "disable_hypervisor": true,
  "usb_legacy": false
}
```

## État d'alimentation et statut d'exécution de la VM

### GET /api/v4/machine\_status/{machine\_id}

**Description**: Récupère le statut d'exécution réel et l'état d'alimentation d'une VM à l'aide de la clé machine.

**Vérifier l'état d'alimentation de la VM**:

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

### Exemple de réponse d'une VM arrêtée

```json
{
  "$key": 54,
  "machine": 54,
  "running": false,
  "migratable": true,
  "node": null,
  "migrated_node": null,
  "migration_destination": null,
  "started": 1755993338,
  "local_time": 0,
  "status": "stopped",
  "status_info": "",
  "state": "offline",
  "powerstate": false,
  "last_update": 1755993358,
  "running_cores": 3,
  "running_ram": 16384,
  "agent_version": "",
  "agent_features": [],
  "agent_guest_info": []
}
```

### Exemple de réponse d'une VM en cours d'exécution

```json
{
  "$key": 44,
  "machine": 44,
  "running": true,
  "migratable": true,
  "node": 3,
  "migrated_node": null,
  "migration_destination": null,
  "started": 1755460982,
  "local_time": 0,
  "status": "running",
  "status_info": "",
  "state": "online",
  "powerstate": true,
  "last_update": 1755993927,
  "running_cores": 6,
  "running_ram": 12288,
  "agent_version": "",
  "agent_features": [],
  "agent_guest_info": []
}
```

{% hint style="success" %}
**État VM vs Machine**

* **Informations sur la VM** (`/api/v4/vms/{vm_key}`): Configuration, paramètres et métadonnées
* **État d’alimentation** (`/api/v4/machine_status/{machine_key}`): Statut d'exécution, état d'alimentation et utilisation des ressources
* Utilisez toujours la clé machine (et non la clé VM) pour vérifier l'état d'alimentation réel et le statut d'exécution
  {% endhint %}

{% hint style="success" %}
**Champs d'état**

* `powerstate`: Booléen indiquant si la VM est sous tension
* `running`: Booléen indiquant si la VM est actuellement en cours d'exécution
* `status`: Statut textuel ("running", "stopped", etc.)
* `state`: État global ("online", "offline")
* `node`: Nœud physique sur lequel la VM s'exécute (null si arrêtée)
  {% endhint %}

## Surveillance de l'état d'alimentation

### Vérification du seul état d'alimentation

Pour des vérifications rapides de l'état d'alimentation, vous pouvez demander des champs spécifiques :

```bash
# Vérifier uniquement l'état d'alimentation
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,running,status" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Réponse**:

```json
{
  "powerstate": true,
  "running": true,
  "status": "running"
}
```

### Surveillance des changements d'état d'alimentation

```python
import time
import requests

def wait_for_power_state(machine_id, desired_state, max_retries=10):
    """Attendre que la VM atteigne l'état d'alimentation souhaité"""
    for attempt in range(max_retries):
        response = requests.get(
            f"https://your-vergeos.example.com/api/v4/machine_status/{machine_id}",
            params={"fields": "powerstate,running,status"},
            headers={"Authorization": "Bearer YOUR_API_KEY"}
        )
        
        data = response.json()
        if data.get("powerstate") == desired_state:
            return True
            
        time.sleep(5)  # Attendre 5 secondes entre les vérifications
    
    return False

# Exemple d'utilisation
if wait_for_power_state("54", True):
    print("La VM est maintenant en cours d'exécution")
else:
    print("La VM n'a pas réussi à démarrer dans le délai imparti")
```

## Flux de travail courants de gestion de l'alimentation

### Flux de travail d'arrêt sécurisé de la VM

```bash
# Étape 1 : Tenter un arrêt gracieux
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": "poweroff", "vm": "42"}'

# Étape 2 : Attendre et vérifier l'état (répéter si nécessaire)
sleep 30
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,status" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Étape 3 : Forcer l'arrêt si l'arrêt gracieux a échoué (après un délai raisonnable)
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"}'
```

### Flux de travail de redémarrage de la VM

```bash
# Étape 1 : Redémarrage gracieux
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": "reset",
    "params": {"graceful": true},
    "vm": "42"
  }'

# Étape 2 : Surveiller la progression du redémarrage
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,status,node" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Gestion des erreurs

### Erreurs courantes de gestion de l'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.

**Erreur**: `409 Conflit - VM non en cours d'exécution`

```json
{
  "error": "Impossible d'éteindre la VM : elle n'est pas en état d'exécution"
}
```

**Solution**: Vérifiez que la VM est bien en cours d'exécution avant de tenter un arrêt.

**Erreur**: `507 Ressources insuffisantes`

```json
{
  "error": "Ressources de cluster insuffisantes pour démarrer la VM"
}
```

**Solution**: Vérifiez la disponibilité des ressources du cluster ou réduisez les besoins en ressources de la VM.

### Délais d'attente des opérations

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

* **Mise sous tension**: 30 à 60 secondes
* **Arrêt gracieux**: 60-120 secondes
* **Arrêt forcé**: 10-30 secondes
* **Redémarrez**: 60-120 secondes

{% 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 créer 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 gestion de l'alimentation 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-power-management.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.