API für erweiterte VM-Operationen

Vollständige Anleitung zu erweiterten VM-Operationen in VergeOS, einschließlich Klonen, Snapshots, Löschen und Fehlerbehebung

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

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

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

Voraussetzungen

VM muss vorhanden sein → Siehe VM-Erstellung

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

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

Beispiel für die Antwort:

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

Erweiterte Klonoptionen

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

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

Beispiel für einen Klon-Workflow

# 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

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

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

Aus Snapshots wiederherstellen

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

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

VM-Snapshots auflisten

GET /api/v4/vms

Verwenden Sie Filter, um Snapshots zu finden:

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:

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

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

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.

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

Ü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)

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

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)

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

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

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.

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

# 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

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

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

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

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

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

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

# 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

# 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

# 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

Verwandte Vorgänge

• VM-Erstellung: Siehe VM-Erstellung für die anfängliche VM-Einrichtung
• Energieverwaltung: Siehe VM-Energieverwaltung für Start-/Stopp-Operationen
• Konfiguration: Siehe VM-Konfiguration für CPU-/RAM-Änderungen

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