> 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/de/automation-api/vm-power-management.md).

# VM-Energieverwaltungs-API

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

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`](/knowledge-base/de/automation-api/vm-creation-api.md) **Häufige nächste Schritte**:

* VM-Einstellungen konfigurieren → [`VM-Konfiguration`](/knowledge-base/de/automation-api/vm-configuration.md)
* Erweiterte Vorgänge → [`Erweiterte VM-Vorgänge`](/knowledge-base/de/automation-api/vm-advanced-operations.md)

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

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

### Voraussetzungen

Die VM muss zuerst erstellt werden → Siehe [`VM-Erstellung`](/knowledge-base/de/automation-api/vm-creation-api.md)

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

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

**Vollständiger API-Aufruf**:

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

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

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

## VMs stoppen

### Ordnungsgemäßes Ausschalten (ACPI)

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

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

**Vollständiger API-Aufruf**:

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

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

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

**Vollständiger API-Aufruf**:

```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" %}
**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.
{% endhint %}

## VMs neu starten

### Ordnungsgemäßer Neustart (ACPI)

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

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

**Vollständiger API-Aufruf**:

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

### Hard-Reset (Power-Cycle)

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

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

**Vollständiger API-Aufruf**:

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

## VM-Status und -Informationen

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

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

**Vollständige VM-Informationen abrufen**:

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

**Beispiel für die Antwort**:

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

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

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

### Beispiel für eine Antwort einer laufenden VM

```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" %}
**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
  {% endhint %}

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

## Überwachung des Energiezustands

### Nur den Energiezustand prüfen

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

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

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

### Änderungen des Energiezustands überwachen

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

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

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

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

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

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

{% hint style="info" %}
**Verwandte Vorgänge**

* **VM-Erstellung**: Siehe [`VM-Erstellung`](/knowledge-base/de/automation-api/vm-creation-api.md) zum Erstellen von VMs
* **Konfiguration**: Siehe [`VM-Konfiguration`](/knowledge-base/de/automation-api/vm-configuration.md) für CPU-/RAM-Änderungen
* **Erweiterte Vorgänge**: Siehe [`Erweiterte VM-Vorgänge`](/knowledge-base/de/automation-api/vm-advanced-operations.md) für Klonen und Snapshots
  {% endhint %}

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