> 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/automate-protect-and-extend/de/integrationen-und-apis/python-sdk.md).

# VergeOS Python SDK (pyvergeos)

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

```bash
pip install pyvergeos
```

### Mit uv

```bash
uv add pyvergeos
```

### Aus dem Quellcode

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

## Authentifizierung

Das SDK unterstützt mehrere Authentifizierungsmethoden:

### Benutzername/Passwort

```python
from pyvergeos import VergeClient

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

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

### API-Token

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

### Umgebungsvariablen

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

```python
client = VergeClient.from_env()
```

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

### Kontextmanager

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

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

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

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

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

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

{% tabs %}
{% tab title="Schlüsselwortargumente" %}

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

{% endtab %}

{% tab title="OData-Filterzeichenfolge" %}

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

{% endtab %}

{% tab title="Filter-Builder" %}

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

{% endtab %}
{% endtabs %}

### Aufgaben warten

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

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

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

## Fehlerbehandlung

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

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

{% hint style="info" %}
**Verfügbare Ausnahmetypen**
{% endhint %}

| 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](https://github.com/verge-io/pyvergeos)
* [PyPI-Paket](https://pypi.org/project/pyvergeos/)

## 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](https://docs.python.org/3/)
* [VergeOS-API-Dokumentation](/knowledge-base/de/automation-api/verge-api-guide.md)
* [PSVergeOS PowerShell-Modul](/automate-protect-and-extend/de/integrationen-und-apis/powershell-module.md) - PowerShell-Alternative
* [Terraform-Provider](/automate-protect-and-extend/de/integrationen-und-apis/terraform-provider.md) - Infrastruktur als Code


---

# 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/automate-protect-and-extend/de/integrationen-und-apis/python-sdk.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.