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

# API für erweiterte VM-Operationen

{% hint style="info" %}
**Wichtige Punkte**

* VMs mit vollständiger Konfiguration und Laufwerkskopie klonen
* VM-Snapshots für Sicherung und Wiederherstellung erstellen und zurückspielen
* VMs sicher löschen mit automatischer Ressourcenbereinigung
* Umfassende Fehlerbehandlung und Fehlerbehebungshinweise
  {% endhint %}

Dieser Leitfaden behandelt fortgeschrittene Operationen mit virtuellen Maschinen in VergeOS, einschließlich Klonen, Snapshot-Verwaltung, Löschung und Fehlerbehebung. Diese Operationen bieten leistungsstarke Funktionen für das VM-Lebenszyklusmanagement und die Notfallwiederherstellung.

**Stufe**: VM-Erweiterte Operationen (4 von 4) **Eingabe**: VM-Schlüssel (42), Operationstyp, Parameter **Ausgabe**: Geklonte VMs, Snapshots, Bestätigung der Bereinigung **Vorherige**: VM konfiguriert → [`VM-Konfiguration`](/knowledge-base/de/automation-api/vm-configuration.md) **Häufige Operationen**:

* Klonen für Vorlagen → Neuer VM-Erstellungszyklus
* Snapshot für Sicherung → Wiederherstellungs-Workflows
* Löschen für Bereinigung → Ende des Lebenszyklus

## Dieses Dokument hilft bei

* "So klonen Sie VMs per API"
* "VM-Snapshots und Sicherungen erstellen"
* "VMs aus Snapshots wiederherstellen"
* "VMs sicher löschen und bereinigen"
* "VM-Fehlerbehebung und Diagnose"
* "Workflows zur Vorlagenerstellung"
* "Notfallwiederherstellungsoperationen"
* "Massenverwaltung von VMs"
* "Automatisierung der Ressourcenbereinigung"

## Kurzreferenz

### Primäre Endpunkte

* **VM-Aktionen**: `POST /api/v4/vm_actions`
* **VM-Löschung**: `DELETE /api/v4/vms/{vm_key}`
* **VM-Auflistung**: `GET /api/v4/vms`

### Wichtige Aktionen

* `klonen`: Vollständige VM-Kopie erstellen
* `Snapshot`: VM-Snapshot erstellen
* `wiederherstellen`: Aus Snapshot wiederherstellen

### Authentifizierung

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

### Voraussetzungen

VM muss vorhanden sein → Siehe [`VM-Erstellung`](/knowledge-base/de/automation-api/vm-creation-api.md)

## API-Kurzreferenz

| Vorgang                   | Methode | Endpunkt                      | Schlüsseltyp        | Zweck                                   |
| ------------------------- | ------- | ----------------------------- | ------------------- | --------------------------------------- |
| VM klonen                 | POST    | `/api/v4/vm_actions`          | VM-Schlüssel        | Vollständige Kopie erstellen            |
| Snapshot erstellen        | POST    | `/api/v4/vm_actions`          | VM-Schlüssel        | Sicherung zu einem bestimmten Zeitpunkt |
| Snapshot wiederherstellen | POST    | `/api/v4/vm_actions`          | VM-Schlüssel        | Wiederherstellungsvorgang               |
| Snapshots auflisten       | GET     | `/api/v4/vms`                 | Filterabfrage       | Snapshots finden                        |
| VM löschen                | DELETE  | `/api/v4/vms/{id}`            | VM-Schlüssel        | Vollständige Entfernung                 |
| VM-Status                 | GET     | `/api/v4/vms/{id}`            | VM-Schlüssel        | Konfigurationsprüfung                   |
| Operationsstatus          | GET     | `/api/v4/machine_status/{id}` | Maschinen-Schlüssel | Laufzeitüberwachung                     |

## Index zur Fehlerbehebung

* **409 Konflikt**: Klonname existiert bereits, VM läuft bereits, Operation läuft
* **507 Unzureichender Speicher**: Nicht genügend Speicherplatz für den Klon, Snapshot-Speicher voll
* **403 Verboten**: API-Schlüssel-Berechtigungen, Zugriff auf VM verweigert, Cluster-Einschränkungen
* **404 Nicht gefunden**: VM nicht gefunden, Snapshot nicht gefunden, ungültiger VM-Schlüssel
* **408 Anforderungs-Timeout**: Zeitüberschreitung beim Klonvorgang, Zeitüberschreitung bei Snapshot-Erstellung
* **422 Nicht verarbeitbare Entität**: Ungültige Klonparameter, Konflikt bei Snapshot-Wiederherstellung
* **500 Interner Serverfehler**: Probleme mit dem Speichersystem, Hypervisor-Probleme, Clusterfehler

## VM-Klonen

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

**Beschreibung**: Erstellt eine vollständige Kopie einer VM einschließlich aller Laufwerke und der Konfiguration.

### Einfacher Klon

```json
{
  "params": {
    "name": "Test-Klon",
    "quiesce": "true"
  },
  "action": "clone",
  "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 '{
    "params": {
      "name": "Test-Klon",
      "quiesce": "true"
    },
    "action": "clone",
    "vm": "42"
  }'
```

**Beispiel für die Antwort**:

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

### Erweiterte Klonoptionen

```json
{
  "params": {
    "name": "production-clone",
    "description": "Produktionsserver-Klon für Tests",
    "preserve_macs": "true",
    "preserve_device_uuids": "true",
    "quiesce": "true",
    "cluster": "2"
  },
  "action": "clone",
  "vm": "42"
}
```

### Klonparameter

| Parameter               | Typ    | Erforderlich | Beschreibung                                                    |
| ----------------------- | ------ | ------------ | --------------------------------------------------------------- |
| name                    | string | Ja           | Name für die geklonte VM                                        |
| description             | string | Nein         | Beschreibung des Klons                                          |
| quiesce                 | string | Nein         | VM vor dem Klonen anhalten ("true"/"false") für Datenkonsistenz |
| preserve\_macs          | string | Nein         | MAC-Adressen beibehalten ("true"/"false")                       |
| preserve\_device\_uuids | string | Nein         | Geräte-UUIDs beibehalten ("true"/"false")                       |
| cluster                 | string | Nein         | Ziel-Cluster-ID                                                 |

{% hint style="success" %}
**Klonoptionen**

* **Anhalten**: Verwenden Sie `"quiesce": "true"` um die Datenkonsistenz sicherzustellen, indem die VM kurz angehalten wird
* **MACs beibehalten**: Verwenden Sie `"preserve_macs": "true"` um dieselben MAC-Adressen beizubehalten (kann Netzwerk-Konflikte verursachen)
* **Geräte-UUIDs beibehalten**: Verwenden Sie `"preserve_device_uuids": "true"` um Gerätekennungen beizubehalten
* **Clusterübergreifend**: Geben Sie eine andere Cluster-ID an, um in einen anderen Cluster zu klonen
  {% endhint %}

### Beispiel für einen Klon-Workflow

```bash
# Schritt 1: Klon erstellen
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": "Automatisierter Backup-Klon",
      "quiesce": "true"
    },
    "action": "clone",
    "vm": "42"
  }'

# Schritt 2: Klonerstellung prüfen (mithilfe des zurückgegebenen vmkey)
curl "https://your-vergeos.example.com/api/v4/vms/43?fields=name,description,created" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Schritt 3: Stromversorgungszustand des Klons prüfen
curl "https://your-vergeos.example.com/api/v4/machine_status/55?fields=powerstate,status" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## VM-Snapshots

### Snapshots erstellen

```json
{
  "vm": "42",
  "action": "snapshot",
  "params": {
    "name": "pre-update-snapshot",
    "description": "Vor Systemaktualisierung"
  }
}
```

**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 '{
    "vm": "42",
    "action": "snapshot",
    "params": {
      "name": "pre-update-snapshot",
      "description": "Vor Systemaktualisierung - $(date)"
    }
  }'
```

### Aus Snapshots wiederherstellen

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

**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 '{
    "vm": "42",
    "action": "restore",
    "params": {
      "snapshot_id": "snapshot-67890"
    }
  }'
```

### VM-Snapshots auflisten

#### GET /api/v4/vms

Verwenden Sie Filter, um Snapshots zu finden:

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

**Alle Snapshots für eine VM finden**:

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

### Workflow zur Snapshot-Verwaltung

```bash
# Schritt 1: Vor Wartungsarbeiten Snapshot erstellen
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": "maintenance-snapshot-$(date +%Y%m%d-%H%M)",
      "description": "Snapshot vor Wartung"
    }
  }'

# Schritt 2: Snapshots auflisten, um Snapshot-ID zu finden
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"

# Schritt 3: Bei Bedarf wiederherstellen (nach Wartungsproblemen)
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": "found-snapshot-id"
    }
  }'
```

## VM-Löschung und Bereinigung

### Vollständige VM-Löschung

#### DELETE /api/v4/vms/{vm\_key}

**Beschreibung**: Löscht eine VM und entfernt automatisch alle zugehörigen Ressourcen einschließlich Laufwerke, NICs, Geräte und Konfigurationen.

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

**Antwort**: `200 OK` bei erfolgreicher Löschung.

{% hint style="success" %}
**Automatische Bereinigung**

Wenn Sie eine VM mit `DELETE /api/v4/vms/{vm_key}`, entfernt VergeOS automatisch:

* **Alle Laufwerke** an der VM angeschlossen
* **Alle Netzwerkschnittstellen** (NICs)
* **Alle Geräte** (GPU, PCI-Passthrough, USB, TPM usw.)
* **VM-Konfiguration** und Metadaten
* **Cloud-init-Dateien** und Konfigurationen
* **VM-Notizen** und Dokumentation
* **Zugehörige Maschinenressourcen**
  {% endhint %}

### Überlegungen vor dem Löschen

Bevor Sie eine VM löschen, beachten Sie:

1. **Datensicherung**: Stellen Sie sicher, dass wichtige Daten gesichert sind
2. **Snapshots**: VM-Snapshots können zusammen mit der VM gelöscht werden
3. **Abhängigkeiten**: Prüfen Sie, ob andere Systeme von dieser VM abhängen
4. **Netzwerkkonfiguration**: Beachten Sie besondere Netzwerkkonfigurationen
5. **Lizenzierung**: Berücksichtigen Sie Auswirkungen auf die Softwarelizenzierung

### Sicherer Löschvorgang

#### Schritt 1: VM ausschalten (empfohlen)

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

#### Schritt 2: Stromversorgungszustand prüfen

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

#### Schritt 3: Abschließende Sicherung erstellen (optional)

```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": "abschließende-sicherung-vor-loeschung",
      "description": "Letzte Sicherung vor dem Löschen der VM"
    },
    "action": "clone",
    "vm": "42"
  }'
```

#### Schritt 4: VM und alle Ressourcen löschen

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

{% hint style="success" %}
**Verwendung des VM-Schlüssels**

Verwenden Sie den VM-Schlüssel (z. B. `42`) aus der Antwort zur VM-Erstellung oder der VM-Auflistung, nicht den Maschinenschlüssel. Der Löschvorgang behandelt automatisch alle zugehörigen Maschinenressourcen.
{% endhint %}

### Keine manuelle Bereinigung erforderlich

Im Gegensatz zu manchen Virtualisierungsplattformen erledigt VergeOS die vollständige Ressourcenbereinigung automatisch. Sie müssen **nicht** nicht manuell:

* Einzelne Laufwerke löschen
* Netzwerkschnittstellen entfernen
* Geräte trennen
* Konfigurationsdateien bereinigen
* Maschinenstatus-Einträge entfernen

Der einzelne `DELETE /api/v4/vms/{vm_key}` Vorgang übernimmt die gesamte Bereinigung automatisch.

### Verwaiste Ressourcen finden

```bash
# Laufwerke ohne zugehörige Maschinen finden
curl "https://your-vergeos.example.com/api/v4/machine_drives?filter=machine%20eq%20null" \
  -H "Authorization: Bearer YOUR_API_KEY"

# NICs ohne zugehörige Maschinen finden
curl "https://your-vergeos.example.com/api/v4/machine_nics?filter=machine%20eq%20null" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Fehlerbehandlung und Fehlerbehebung

### Häufige Fehlerszenarien

#### Fehler bei der VM-Erstellung

**Fehler**: `400 Ungültige Anfrage - Ungültiger Maschinentyp`

```json
{
  "error": "Ungültiger machine_type 'invalid-type'. Gültige Optionen: pc, q35, pc-i440fx-*, pc-q35-*"
}
```

**Lösung**: Verwenden Sie gültige Maschinentypen aus der unterstützten Liste.

#### Konflikte beim Power-Status

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

#### Ressourcenbeschränkungen

**Fehler**: `507 Unzureichender Speicher`

```json
{
  "error": "Unzureichender Speicherplatz in Tier 3 für die angeforderte Festplattengröße"
}
```

**Lösung**: Wählen Sie einen anderen Speichertier oder reduzieren Sie die Festplattengröße.

#### Klonfehler

**Fehler**: `409 Konflikt - Klonname existiert bereits`

```json
{
  "error": "VM mit dem Namen 'test clone' existiert bereits"
}
```

**Lösung**: Verwenden Sie eindeutige Namen für geklonte VMs.

### VM-Operationen überwachen

#### Operationsstatus prüfen

Viele VM-Operationen sind asynchron. Überwachen Sie den Fortschritt mit:

```bash
# VM-Status prüfen
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=machine%23status" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Maschinenstatus für Laufzeitinformationen prüfen
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=status,powerstate" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Zeitüberschreitungen bei Operationen

Legen Sie angemessene Zeitlimits für lang laufende Operationen fest:

* **VM-Erstellung**: 5–10 Minuten
* **Klonoperationen**: 10–30 Minuten (je nach Größe)
* **Snapshot-Erstellung**: 2–5 Minuten
* **Snapshot-Wiederherstellung**: 5–15 Minuten
* **Änderungen des Stromversorgungszustands**: 30–60 Sekunden
* **VM-Löschung**: 2–5 Minuten

### Wiederholungslogik

Implementieren Sie eine Wiederholungslogik für vorübergehende Fehler:

```python
import time
import requests

def wait_for_operation_completion(vm_id, max_retries=20):
    """Warten, bis die VM-Operation abgeschlossen ist"""
    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)  # 10 Sekunden zwischen den Prüfungen warten
    
    return False

# Beispielverwendung
if wait_for_operation_completion("42"):
    print("Operation erfolgreich abgeschlossen")
else:
    print("Operation zeitlich überschritten")
```

### VM-Probleme debuggen

#### VM-Konfiguration prüfen

```bash
# Vollständige VM-Konfiguration abrufen
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=most" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Maschinenstatus prüfen

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

#### Systemressourcen prüfen

```bash
# Clusterressourcen prüfen
curl "https://your-vergeos.example.com/api/v4/clusters/1?fields=resources" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Speichertiers prüfen
curl "https://your-vergeos.example.com/api/v4/storage_tiers" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Bewährte Verfahren

1. **Operationen immer zuerst** in Entwicklungsumgebungen testen
2. **Snapshots erstellen** vor größeren Änderungen
3. **Ressourcennutzung überwachen** während der Operationen
4. **Ordentliche Fehlerbehandlung implementieren** in Automatisierungsskripten
5. **Beschreibende Namen verwenden** für Klone und Snapshots
6. **Unbenutzte Ressourcen bereinigen** regelmäßig
7. **Betriebsverfahren dokumentieren** für Ihr Team

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

* **VM-Erstellung**: Siehe [`VM-Erstellung`](/knowledge-base/de/automation-api/vm-creation-api.md) für die anfängliche VM-Einrichtung
* **Energieverwaltung**: Siehe [`VM-Energieverwaltung`](/knowledge-base/de/automation-api/vm-power-management.md) für Start-/Stopp-Operationen
* **Konfiguration**: Siehe [`VM-Konfiguration`](/knowledge-base/de/automation-api/vm-configuration.md) für CPU-/RAM-Änderungen
  {% endhint %}

{% hint style="info" %}
**Brauchen Sie Hilfe?**

Für zusätzlichen Support bei erweiterten VM-Operationen:

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