VergeOS Python SDK (pyvergeos)

pyvergeos ist ein Python-SDK zur Verwaltung von VergeOS über die REST-API und bietet eine Python-ähnliche, mit Typannotationen versehene Schnittstelle zur Automatisierung von VMs, Netzwerken, Speicher, Tenants und Notfallwiederherstellung.

Überblick

pyvergeos ist ein Python-SDK zur Verwaltung der VergeOS-Infrastruktur über die REST-API. Es bietet eine Python-ähnliche, mit Typannotationen versehene Oberfläche für die Automatisierung des VM-Lebenszyklus, von Netzwerken, Speicher, Multi-Tenant-Operationen und Disaster-Recovery-Workflows und ist damit ideal für Automatisierungsskripte, die Entwicklung von Tools und Integrationen.

Hauptfunktionen

• VM-Verwaltung: Erstellung, Konfiguration, Stromsteuerung, Klonen und Snapshots
• Erweiterte Netzwerktechnik: Virtuelle Netzwerke, Firewall-Regeln, DHCP, DNS, IPSec VPN und WireGuard
• NAS & Speicher: Volumenverwaltung, CIFS/NFS-Freigaben und Synchronisierung
• Multi-Tenancy: Mandantenbereitstellung mit Ressourcenisolierung
• Disaster Recovery: Cloud-Snapshots, Standort-Synchronisierung und Wiederherstellungs-Workflows
• Filterung: OData-Filterunterstützung mit einer Fluent-API für den Filter-Builder
• Typannotationen: Vollständige Typ-Hinweise für IDE-Autovervollständigung und statische Analyse
• Plattformübergreifend: Unterstützung für Windows, macOS und Linux

Anforderungen

• Python 3.9 oder höher
• VergeOS 26.0 oder höher

Installation

Von PyPI (empfohlen)

pip install pyvergeos

Mit uv

uv add pyvergeos

Aus dem Quellcode

git clone https://github.com/verge-io/pyvergeos.git
cd pyvergeos
pip install .

Authentifizierung

Das SDK unterstützt mehrere Authentifizierungsmethoden:

Benutzername/Passwort

from pyvergeos import VergeClient

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret",
    verify_ssl=False  # Für selbstsignierte Zertifikate
)

SSL-Zertifikatsprüfung

Setzen Sie verify_ssl=False nur für Umgebungen mit selbstsignierten Zertifikaten. In Produktionsumgebungen mit gültigen Zertifikaten lassen Sie diesen Parameter weg oder setzen Sie ihn auf True.

API-Token

client = VergeClient(
    host="192.168.1.100",
    token="your-api-token"
)

Umgebungsvariablen

export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret

client = VergeClient.from_env()

Empfohlen für die Produktion

Die Verwendung von Umgebungsvariablen hält Anmeldedaten aus Ihrem Quellcode heraus und erleichtert die Verwendung unterschiedlicher Anmeldedaten in verschiedenen Umgebungen.

Kontextmanager

with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()

Automatische Bereinigung

Die Verwendung des Kontextmanagers (with Anweisung) stellt sicher, dass die Verbindung ordnungsgemäß geschlossen wird, selbst wenn eine Ausnahme auftritt.

Verfügbare Ressourcen

Das SDK bietet Zugriff auf die folgenden VergeOS-Ressourcen:

Kategorie	Ressourcen
Virtuelle Maschinen	VMs, Laufwerke, NICs, Snapshots
Netzwerk	Netzwerke, Regeln, DNS, DHCP, Aliase, Hosts
VPN	IPSec-Verbindungen, WireGuard-Interfaces und Peers
NAS/Speicher	Dienste, Volumes, CIFS/NFS-Freigaben, Volumen-Synchronisierungen
Mandanten	Mandantenverwaltung, Snapshots, Speicher, Netzwerkblöcke
Benutzer & Gruppen	Benutzer, Gruppen, Berechtigungen, API-Schlüssel
System	Cluster, Knoten, Speicherstufen, Zertifikate
Überwachung	Alarme, Protokolle, Aufgaben
Sicherung & DR	Snapshot-Profile, Cloud-Snapshots, Standorte, Standort-Synchronisierungen

Anwendungsbeispiele

Virtuelle Maschinen verwalten

from pyvergeos import VergeClient

client = VergeClient(host="192.168.1.100", username="admin", password="secret")

# Alle VMs auflisten
for vm in client.vms.list():
    print(f"{vm.name}: {vm.ram} MB RAM, {vm.cpu_cores} Kerne")

# Eine bestimmte VM abrufen
vm = client.vms.get(name="web-server")

# Eine VM erstellen
new_vm = client.vms.create(
    name="test-vm",
    ram=2048,
    cpu_cores=2,
    os_family="linux"
)

# Stromoperationen
vm.power_on()
vm.power_off()
vm.reset()

# Snapshots
vm.snapshot(retention=86400, quiesce=True)

# Eine VM klonen
clone = vm.clone(name="test-clone")

# Laufwerke und NICs hinzufügen
vm.drives.add(name="data", size=50*1024*1024*1024)
vm.nics.add(network=network.key)

client.disconnect()

Netzwerke erstellen und verwalten

# Ein virtuelles Netzwerk erstellen
network = client.networks.create(
    name="app-network",
    network_address="10.10.1.0/24",
    ip_address="10.10.1.1",
    dhcp_enabled=True
)

network.power_on()
network.apply_rules()

# Firewall-Regeln hinzufügen
network.rules.create(
    name="Allow SSH",
    action="accept",
    protocol="tcp",
    dest_port=22
)

Ressourcen filtern

Das SDK unterstützt mehrere Filteransätze:

Schlüsselwortargumente

# Einfach und lesbar für grundlegende Filter
vms = client.vms.list(status="running", name="prod-*")

OData-Filterzeichenfolge

# Vollständige OData-Filter-Syntax für komplexe Abfragen
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")

Filter-Builder

# Fluent API zum programmatischen Erstellen von Filtern
from pyvergeos import Filter

f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))

Aufgaben warten

Viele Operationen in VergeOS laufen asynchron ab. Verwenden Sie den Task-Manager, um auf den Abschluss zu warten:

result = vm.snapshot()
task = client.tasks.wait(result["task"], timeout=300)

Asynchrone Operationen

Operationen wie Snapshots, Klone und Migrationen geben sofort mit einer Task-ID zurück. Verwenden Sie client.tasks.wait() um zu blockieren, bis die Operation abgeschlossen ist.

Fehlerbehandlung

Das SDK stellt spezifische Ausnahmetypen für verschiedene Fehlerbedingungen bereit:

from pyvergeos import NotFoundError, AuthenticationError, TaskTimeoutError

try:
    vm = client.vms.get(name="nonexistent")
except NotFoundError:
    print("VM nicht gefunden")

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"Aufgabe {e.task_id} hat die Zeitüberschreitung überschritten")

Verfügbare Ausnahmetypen

Ausnahme	Beschreibung
VergeError	Basisausnahme für alle SDK-Fehler
AuthenticationError	Ungültige Anmeldedaten oder abgelaufener Token
NotFoundError	Angeforderte Ressource existiert nicht
ConflictError	Konflikt im Ressourcenstatus (z. B. VM läuft bereits)
ValidationError	Ungültige Parameterwerte
TaskTimeoutError	Aufgabe wurde innerhalb der Zeitüberschreitung nicht abgeschlossen
TaskError	Aufgabe ist während der Ausführung fehlgeschlagen

Häufige Anwendungsfälle

• Infrastrukturautomatisierung: VMs, Netzwerke und Speicher programmatisch bereitstellen
• CI/CD-Integration: Testumgebungen in Pipelines erstellen und zerstören
• Überwachung und Berichterstellung: Ressourcenstatus abfragen und Bestandsberichte erstellen
• Backup-Automatisierung: Snapshots und Cloud-Backups planen und verwalten
• Multi-Tenant-Bereitstellung: Mandantenerstellung und Ressourcenzuweisung automatisieren

Dokumentation und Ressourcen

Die vollständige Dokumentation, einschließlich aller verfügbaren Methoden und detaillierter Anwendungsbeispiele, finden Sie im offiziellen Repository:

• GitHub-Repository
• PyPI-Paket

Support

Wenn Sie auf Probleme stoßen oder Funktionswünsche haben, eröffnen Sie bitte ein Issue im GitHub-Repository:

https://github.com/verge-io/pyvergeos/issues

Weitere Ressourcen

• Python-Dokumentation
• VergeOS-API-Dokumentation
• PSVergeOS PowerShell-Modul - PowerShell-Alternative
• Terraform-Provider - Infrastruktur als Code