Python-SDK (pyvergeos)

Automatisieren Sie die VergeOS-Infrastruktur mit dem pyvergeos-Python-SDK — VM-Lebenszyklus, Netzwerk, Multi-Tenancy, Speicher und Disaster Recovery aus Python-Skripten heraus.

Das pyvergeos Das SDK bietet eine Python-ähnliche, typannotierte Schnittstelle für die gesamte VergeOS-REST-API. Anstatt rohe HTTP-Anfragen zu erstellen, arbeiten Sie mit Ressourcenmanagern — client.vms, client.networks, client.tenants — die direkt auf VergeOS-Objekte abgebildet werden. Das SDK übernimmt Authentifizierung, Paginierung, Wiederholungsversuche und das Polling asynchroner Aufgaben, damit Ihre Automatisierungsskripte sauber und auf die Geschäftslogik fokussiert bleiben.

Voraussetzungen & Installation

Voraussetzungen:

• Python 3.9 oder höher
• VergeOS 26.0 oder höher
• Läuft auf Windows, macOS und Linux

Installation von PyPI (empfohlen):

pip install pyvergeos

Oder mit uv (schnellere Alternative):

uv add pyvergeos

Aus dem Quellcode (Entwicklung):

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

Authentifizierung

Das SDK unterstützt drei Authentifizierungsmethoden, die jeweils für unterschiedliche Umgebungen geeignet sind.

Benutzername & Passwort

Der einfachste Ansatz für interaktive Skripte und die Entwicklung:

from pyvergeos import VergeClient

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

API-Token

Für Produktionsautomatisierung, wenn Sie einen vorab erzeugten API-Schlüssel haben:

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

Umgebungsvariablen

Der empfohlene Ansatz für die Produktion — hält Zugangsdaten aus dem Quellcode heraus:

export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret
export VERGE_VERIFY_SSL=false      # Optional
export VERGE_TIMEOUT=30            # Optional
export VERGE_RETRY_TOTAL=3         # Optional
export VERGE_RETRY_BACKOFF=1       # Optional

client = VergeClient.from_env()

Kontextmanager

Verwenden Sie in Produktionscode immer den Kontextmanager, um sicherzustellen, dass Verbindungen ordnungsgemäß geschlossen werden, auch wenn Ausnahmen auftreten:

with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()
    for vm in vms:
        print(f"{vm.name}: {vm.ram}MB RAM")
# Verbindung wird hier automatisch geschlossen

Ressourcenmanager

Jeder VergeOS-Ressourcentyp wird über einen Ressourcenmanager am Client-Objekt bereitgestellt. Jeder Manager bietet konsistente list(), get(), create()- und Aktionsmethoden.

Virtuelle Maschinen

client.vms — VMs erstellen, konfigurieren, ein-/ausschalten, klonen, Snapshots erstellen und Laufwerke/NICs verwalten.

Netzwerke

client.networks — Virtuelle Netzwerke, Firewall-Regeln, DHCP, DNS und Netzwerk-Energieverwaltung.

Mandanten

client.tenants — Mandantenübergreifende Bereitstellung, Ressourcenisolierung, Snapshots, Speicher- und Netzwerkblöcke.

NAS & Speicher

client.nas — NAS-Dienste, Volumes, CIFS/NFS-Freigaben und Volumesynchronisierung.

Notfallwiederherstellung

client.dr — Cloud-Snapshots, Standort-Synchronisierung und Wiederherstellungs-Workflows.

Benutzer & Gruppen

client.users — Benutzerkonten, Gruppen, Berechtigungen und API-Schlüsselverwaltung.

Aufgaben & Monitoring

client.tasks — Verfolgung asynchroner Aufgaben, Warten, Timeouts. Außerdem: Alarme und Protokolle.

System & GPU

client.clusters, client.nodes, client.gpu — Cluster-/Knoteninformationen, Speicherebenen, GPU-Geräteverwaltung.

Vollständige Ressourcentabelle

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

Ressourcen filtern

Das SDK bietet drei Ansätze zum Filtern von Ressourcen, von einfachen Schlüsselwortargumenten bis hin zu einem vollständigen OData-Filter-Builder.

Schlüsselwortargumente

Der einfachste Ansatz für grundlegende Filter — Feldnamen direkt übergeben:

# Alle laufenden Linux-VMs finden
vms = client.vms.list(status="running", os_family="linux")

# Platzhalterabgleich
vms = client.vms.list(name="prod-*")

OData-Filterzeichenfolgen

Für komplexe Abfragen rohe OData-Filterausdrücke übergeben:

# Bedingungen mit Operatoren kombinieren
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")

Filter-Builder (Fluent API)

Filter programmgesteuert mit Typsicherheit und Autovervollständigung erstellen:

from pyvergeos import Filter

# Fluentes Verkettung mit Operator-Methoden
f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))

Verfügbare Filteroperatoren:

Methode	OData-Operator	Beispiel
.eq()	eq	Filter().eq("status", "running")
.ne()	ne	Filter().ne("os_family", "windows")
.gt()	gt	Filter().gt("ram", 4096)
.lt()	lt	Filter().lt("cpu_cores", 8)
.ge()	ge	Filter().ge("ram", 2048)
.le()	le	Filter().le("ram", 8192)
.and_()	und	Mehrere Bedingungen verketten
.or_()	oder	Alternative Bedingungen kombinieren

Asynchrone Aufgabenverarbeitung

Viele VergeOS-Operationen — Snapshots, Klone, Migrationen — laufen asynchron und geben sofort eine Aufgaben-ID zurück. Das SDK stellt einen Aufgabenmanager zum Abfragen des Abschlusses bereit:

# Snapshot gibt einen Aufgabenverweis zurück
result = vm.snapshot(retention=86400, quiesce=True)

# Warten, bis der Snapshot abgeschlossen ist (blockiert bis zu 300 Sekunden)
task = client.tasks.wait(result["task"], timeout=300)
print(f"Snapshot abgeschlossen: {task}")

Wenn die Aufgabe innerhalb des Timeouts nicht abgeschlossen wird, wird ein TaskTimeoutError ausgelöst, mit der task_id -Eigenschaft, damit Sie den Status später prüfen können:

from pyvergeos import TaskTimeoutError

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"Aufgabe {e.task_id} läuft noch — später erneut prüfen")

Fehlerbehandlung

Das SDK bietet eine strukturierte Ausnahmehierarchie, sodass Sie bestimmte Fehlermodi gezielt abfangen können:

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

from pyvergeos import NotFoundError, AuthenticationError

try:
    vm = client.vms.get(name="nonexistent-vm")
except NotFoundError:
    print("VM nicht gefunden — Name überprüfen")
except AuthenticationError:
    print("Authentifizierung fehlgeschlagen — Zugangsdaten überprüfen")

Retry-Konfiguration

Das SDK wiederholt vorübergehende Fehler automatisch (HTTP 429, 500, 502, 503, 504) mit exponentiellem Backoff:

client = VergeClient(
    host="192.168.1.100",
    token="api-token",
    retry_total=5,            # Maximale Anzahl von Wiederholungsversuchen (Standard: 3)
    retry_backoff_factor=2,   # Backoff-Multiplikator (Standard: 1)
)

Setzen Sie retry_total=0 um Wiederholungen für zeitkritische Vorgänge vollständig zu deaktivieren.

Mandanten-Kontextwechsel

pyvergeos kann in Mandantenkontexte verbinden vom Host-System aus und ermöglicht zentrale Automatisierungsskripte, die Ressourcen über mehrere Mandanten hinweg verwalten:

# Einen Mandanten aus dem Host-System abrufen
tenant = client.tenants.get(name="customer-a")

# In den Kontext des Mandanten verbinden
tenant_client = tenant.connect()

# Jetzt Ressourcen INNERHALB des Mandanten verwalten
tenant_vms = tenant_client.vms.list()
for vm in tenant_vms:
    print(f"Mandanten-VM: {vm.name}")

# Ein Netzwerk innerhalb des Mandanten erstellen
tenant_client.networks.create(
    name="tenant-app-net",
    network_address="10.50.1.0/24",
    ip_address="10.50.1.1",
    dhcp_enabled=True
)

Dies ist besonders wertvoll für MSPs und Dienstanbieter die die Bereitstellung über Dutzende oder Hunderte von Mandantenumgebungen mit einem einzigen Skript automatisieren müssen.

Praktische Beispiele

Verwaltung des VM-Lebenszyklus

with VergeClient.from_env() as client:
    # Eine neue VM erstellen
    vm = client.vms.create(
        name="web-server-01",
        ram=4096,
        cpu_cores=2,
        os_family="linux"
    )

    # Ein 50-GB-Datenlaufwerk hinzufügen
    vm.drives.add(name="data", size=50 * 1024 * 1024 * 1024)

    # Mit einem Netzwerk verbinden
    network = client.networks.get(name="app-network")
    vm.nics.add(network=network.key)

    # Einschalten
    vm.power_on()
    print(f"VM {vm.name} läuft")

Netzwerk mit Firewall-Regeln

with VergeClient.from_env() as client:
    # Ein Netzwerk erstellen
    network = client.networks.create(
        name="web-tier",
        network_address="10.20.1.0/24",
        ip_address="10.20.1.1",
        dhcp_enabled=True
    )
    network.power_on()

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

Massenoperationen mit Filterung

with VergeClient.from_env() as client:
    # Alle laufenden Produktions-VMs snapshotten
    prod_vms = client.vms.list(name="prod-*", status="running")

    for vm in prod_vms:
        result = vm.snapshot(retention=86400, quiesce=True)
        task = client.tasks.wait(result["task"], timeout=300)
        print(f"Snapshot für {vm.name} erstellt")

Mandantenübergreifender Inventarbericht

with VergeClient.from_env() as client:
    for tenant in client.tenants.list():
        tenant_client = tenant.connect()
        vms = tenant_client.vms.list()
        print(f"\n--- {tenant.name} ---")
        for vm in vms:
            print(f"  {vm.name}: {vm.ram}MB RAM, {vm.cpu_cores} Kerne")

Wichtige Hinweise

Thread-Sicherheit

Der pyvergeos-Client ist nicht threadsicher. Wenn Sie parallele Vorgänge benötigen, erstellen Sie separate VergeClient -Instanzen für jeden Thread. Für wirklich parallele Workloads sollten Sie das govergeos Go-SDK in Betracht ziehen, das für die gleichzeitige Nutzung mit Goroutinen ausgelegt ist.

Kommen Sie von VMware oder Nutanix?

pyvergeos stellt drei Muster bereit, die Sie von Anfang an kennen sollten:

• Filtern — ein flüssiger Filter() -Builder erzeugt OData-ähnliche Ausdrücke (.eq(), .gt(), .and_(), .or_()), oder Sie können einen rohen OData-String an list(filter=...).
• Aufgaben-Polling — asynchrone Vorgänge geben einen Aufgabenverweis zurück; client.tasks.wait(task_id, timeout=...) blockiert bis zum Abschluss und löst bei TaskTimeoutError ein Timeout aus.
• Mandantenkontext — tenant.connect() liefert einen Client, der innerhalb des Mandanten kontextgebunden ist, sodass dasselbe Skript das Host-System und jeden untergeordneten Mandanten steuern kann, ohne eine Verbindung zu einem anderen Endpunkt herzustellen.

Zusätzliche Ressourcen

• GitHub-Repository — Quellcode, Issues und Beiträge
• PyPI-Paket — Neueste Version und Versionsverlauf
• VergeOS-API-Dokumentation