API für VM-Energieverwaltung

Vollständige Anleitung zur Verwaltung der Energiestatus von VMs in VergeOS, einschließlich Starten, Stoppen, Neustarten und Überwachen des Energiestatus

Wichtige Punkte

VM-Energiezustände über REST-API-Endpunkte steuern
Unterstützung für sanfte und erzwungene Energieoperationen
VM-Energiezustand und Laufzeitstatus überwachen
Verstehen Sie VM-Schlüssel vs. Machine-Key für verschiedene Statusprüfungen

Dieser Leitfaden behandelt die Verwaltung von Energiezuständen virtueller Maschinen in VergeOS, einschließlich Starten, Stoppen, Neustarten und Überwachen von VMs. Die VergeOS-API bietet umfassende Funktionen für die Energieverwaltung mit sowohl sanften als auch erzwungenen Operationen.

Stufe: VM-Energiemanagement (2 von 4) Eingabe: VM-Schlüssel (42) aus der Erstellung, Typ der Energieoperation Ausgabe: Änderungen des Energiezustands, Laufzeitstatus Vorherige: VM erstellt → VM-Erstellung Häufige nächste Schritte:

VM-Einstellungen konfigurieren → VM-Konfiguration
Erweiterte Vorgänge → Erweiterte VM-Vorgänge

Dieses Dokument hilft bei

"Wie man VMs über die API startet/stoppt"
"VM-Energiestatus prüfen"
"Sanftes vs. erzwungenes Herunterfahren der VM"
"VM-Neustart- und Zurücksetzungsoperationen"
"Überwachung des VM-Energiezustands"
"Automatisierung des Energiemanagements"
"Fehlerbehebung beim VM-Start"
"Geplante Energieoperationen"
"Ressourcenoptimierung durch Energiesteuerung"

Kurzreferenz

Primäre Endpunkte

Energieaktionen: POST /api/v4/vm_actions
VM-Status: GET /api/v4/vms/{id}
Energiezustand: GET /api/v4/machine_status/{machine_id}

Wichtige Aktionen

poweron: VM starten
poweroff: Ordnungsgemäßes Herunterfahren (ACPI)
kill: Erzwungenes Ausschalten
reset: VM neu starten

Authentifizierung

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

Voraussetzungen

Die VM muss zuerst erstellt werden → Siehe VM-Erstellung

API-Kurzreferenz

Vorgang

Methode

Endpunkt

Schlüsseltyp

Zweck

Einschalten

POST

/api/v4/vm_actions

VM-Schlüssel

Virtuelle Maschine starten

Ausschalten

POST

/api/v4/vm_actions

VM-Schlüssel

Ordnungsgemäßes Herunterfahren (ACPI)

Ausschalten erzwingen

POST

/api/v4/vm_actions

VM-Schlüssel

Sofortige Beendigung

Starten Sie

POST

/api/v4/vm_actions

VM-Schlüssel

VM neu starten

VM-Informationen

GET

/api/v4/vms/{id}

VM-Schlüssel

Konfigurationsdaten

Energiezustand

GET

/api/v4/machine_status/{id}

Maschinen-Schlüssel

Laufzeitstatus

Index zur Fehlerbehebung

409 Konflikt: VM läuft bereits, VM läuft nicht, Abweichung beim Energiezustand
507 Unzureichende Ressourcen: Nicht genügend Cluster-Ressourcen, Speicher/CPU nicht verfügbar
403 Verboten: API-Schlüssel-Berechtigungen, Clusterzugriff verweigert, VM-Zugriff eingeschränkt
404 Nicht gefunden: Ungültiger VM-Schlüssel, VM gelöscht, Machine-Key nicht gefunden
408 Anforderungs-Timeout: Zeitüberschreitung bei der Energieoperation, VM reagiert nicht, Fehler bei der Clusterkommunikation
500 Interner Serverfehler: Hypervisor-Probleme, Knotenprobleme, Speicherausfälle

VMs starten

POST /api/v4/vm_actions

Beschreibung: Schaltet eine virtuelle Maschine ein und wartet, bis sie den laufenden Zustand erreicht.

Einschaltanforderung:

{
  "action": "poweron",
  "params": {},
  "vm": "42"
}

Vollständiger API-Aufruf:

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"
  }'

Antwort: 201 Erstellt wenn die Aktion ausgelöst wird.

Bewährte Verfahren

Überprüfen Sie immer die VM-Konfiguration, bevor Sie sie einschalten
Stellen Sie sicher, dass alle erforderlichen Laufwerke und Netzwerkschnittstellen verbunden sind
Prüfen Sie die Verfügbarkeit der Cluster-Ressourcen
Stellen Sie sicher, dass die VM nicht bereits läuft, um Konflikte zu vermeiden

VMs stoppen

Ordnungsgemäßes Ausschalten (ACPI)

Beschreibung: Sendet ein ACPI-Herunterfahrsignal an das Gastbetriebssystem, sodass es sauber herunterfahren kann.

{
  "action": "poweroff",
  "vm": "42"
}

Vollständiger API-Aufruf:

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"
  }'

Erzwungenes Ausschalten (Kill)

Beschreibung: Beendet die VM sofort, ohne dem Gastbetriebssystem ein sauberes Herunterfahren zu ermöglichen. Verwenden Sie dies nur, wenn das ordnungsgemäße Herunterfahren fehlschlägt.

{
  "action": "kill",
  "vm": "42"
}

Vollständiger API-Aufruf:

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"
  }'

Erzwungenes Ausschalten

Die Verwendung von kill kann zu Datenverlust oder -beschädigung führen. Versuchen Sie immer zuerst das ordnungsgemäße poweroff und verwenden Sie kill nur wenn nötig.

VMs neu starten

Ordnungsgemäßer Neustart (ACPI)

Beschreibung: Sendet ein ACPI-Resetsignal an das Gastbetriebssystem für einen sauberen Neustart.

{
  "action": "reset",
  "params": {
    "graceful": true
  },
  "vm": "42"
}

Vollständiger API-Aufruf:

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"
  }'

Hard-Reset (Power-Cycle)

Beschreibung: Startet die VM sofort neu, ohne dem Gastbetriebssystem ein sauberes Herunterfahren zu ermöglichen.

{
  "action": "reset",
  "vm": "42"
}

Vollständiger API-Aufruf:

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"
  }'

VM-Status und -Informationen

GET /api/v4/vms/{id}

Beschreibung: Ruft VM-Konfiguration und Metadaten mithilfe verschiedener Feldfilter ab.

Vollständige VM-Informationen abrufen:

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

Beispiel für die Antwort:

{
  "$key": 42,
  "name": "Test",
  "machine": 54,
  "description": "Test-VM",
  "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": "Dies ist eine Test-VM",
  "power_cycle_timeout": 0,
  "allow_export": true,
  "creator": "admin",
  "nested_virtualization": true,
  "disable_hypervisor": true,
  "usb_legacy": false
}

VM-Energiezustand und Laufzeitstatus

GET /api/v4/machine_status/{machine_id}

Beschreibung: Ruft den tatsächlichen Laufzeitstatus und Energiezustand einer VM mithilfe des Machine-Key ab.

VM-Energiezustand prüfen:

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

Beispiel für eine Antwort einer gestoppten VM

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

Beispiel für eine Antwort einer laufenden VM

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

VM- vs. Machine-Status

VM-Informationen (/api/v4/vms/{vm_key}): Konfiguration, Einstellungen und Metadaten
Energiezustand (/api/v4/machine_status/{machine_key}): Laufzeitstatus, Energiezustand und Ressourcennutzung
Verwenden Sie immer den Machine-Key (nicht den VM-Key), um den tatsächlichen Energiezustand und Laufzeitstatus zu prüfen

Statusfelder

powerstate: Boolescher Wert, der angibt, ob die VM eingeschaltet ist
running: Boolescher Wert, der angibt, ob die VM derzeit läuft
status: Textstatus ("running", "stopped" usw.)
state: Gesamtstatus ("online", "offline")
node: Auf welchem physischen Knoten die VM läuft (null, wenn gestoppt)

Überwachung des Energiezustands

Nur den Energiezustand prüfen

Für schnelle Überprüfungen des Energiezustands können Sie bestimmte Felder anfordern:

# Nur den Energiezustand prüfen
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,running,status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Antwort:

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

Änderungen des Energiezustands überwachen

import time
import requests

def wait_for_power_state(machine_id, desired_state, max_retries=10):
    """Warten Sie, bis die VM den gewünschten Energiezustand erreicht hat"""
    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)  # Warten Sie 5 Sekunden zwischen den Prüfungen
    
    return False

# Beispielverwendung
if wait_for_power_state("54", True):
    print("VM läuft jetzt")
else:
    print("VM konnte innerhalb des Timeouts nicht gestartet werden")

Häufige Workflows für das Energiemanagement

Sicherer VM-Herunterfahr-Workflow

# Schritt 1: Versuch des ordnungsgemäßen Herunterfahrens
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"}'

# Schritt 2: Warten und Status prüfen (bei Bedarf wiederholen)
sleep 30
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,status" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Schritt 3: Ausschalten erzwingen, wenn das ordnungsgemäße Herunterfahren fehlschlägt (nach angemessener Zeitüberschreitung)
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"}'

VM-Neustart-Workflow

# Schritt 1: Ordentlicher Neustart
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"
  }'

# Schritt 2: Neustartfortschritt überwachen
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,status,node" \
  -H "Authorization: Bearer YOUR_API_KEY"

Fehlerbehandlung

Häufige Fehler beim Energiemanagement

Fehler: 409 Konflikt - VM läuft bereits

{
  "error": "VM kann nicht eingeschaltet werden: bereits im laufenden Zustand"
}

Lösung: Prüfen Sie den aktuellen Stromversorgungszustand, bevor Sie Einschaltbefehle senden.

Fehler: 409 Konflikt - VM läuft nicht

{
  "error": "Cannot power off VM: not in running state"
}

Lösung: Stellen Sie sicher, dass die VM tatsächlich läuft, bevor Sie versuchen, sie herunterzufahren.

Fehler: 507 Unzureichende Ressourcen

{
  "error": "Insufficient cluster resources to start VM"
}

Lösung: Prüfen Sie die Verfügbarkeit der Cluster-Ressourcen oder reduzieren Sie die Ressourcenanforderungen der VM.

Zeitüberschreitungen bei Operationen

Setzen Sie geeignete Timeouts für Energieoperationen:

Einschalten: 30–60 Sekunden
Ordnungsgemäßes Herunterfahren: 60-120 Sekunden
Erzwungenes Herunterfahren: 10-30 Sekunden
Starten Sie: 60-120 Sekunden

Verwandte Vorgänge

VM-Erstellung: Siehe VM-Erstellung zum Erstellen von VMs
Konfiguration: Siehe VM-Konfiguration für CPU-/RAM-Änderungen
Erweiterte Vorgänge: Siehe Erweiterte VM-Vorgänge für Klonen und Snapshots

Brauchen Sie Hilfe?

Für weitere Unterstützung beim VM-Energiemanagement:

Prüfen Sie das VergeOS-Dokumentationsportal
Wenden Sie sich mit konkreten Fehlermeldungen an den VergeOS-Support
Prüfen Sie die Systemprotokolle auf detaillierte Fehlerinformationen
Konsultieren Sie die VergeOS-Community-Foren

VorherigeÜberblick über die API für VM-Lifecycle-Management

NächsteSystemadministration

Zuletzt aktualisiert vor 3 Monaten

War das hilfreich?