API de gestion de l’alimentation des VM

Guide complet pour gérer les états d’alimentation des VM dans VergeOS, y compris le démarrage, l’arrêt, le redémarrage et la surveillance de l’état d’alimentation

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

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 Étapes suivantes courantes:

• Configurer les paramètres de la VM → Configuration de la VM
• Opérations avancées → Opérations avancées de la VM

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

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

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

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

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

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.

{
  "action": "poweroff",
  "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 '{
    "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.

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

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.

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.

{
  "action": "reset",
  "params": {
    "graceful": true
  },
  "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 '{
    "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.

{
  "action": "reset",
  "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 '{
    "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:

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

Exemple de réponse:

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

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

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

{
  "$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": []
}

É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

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)

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 :

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

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

Surveillance des changements d'état d'alimentation

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

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

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

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

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

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

Opérations associées

• Création de VM: Voir Création de VM pour créer 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 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