REST-API & CLI-Tools

Beherrschen Sie die VergeOS-REST-API, das Hilfsskript yb-api und das vrg-CLI für die programmatische Infrastrukturverwaltung und Automatisierung.

Jede Operation, die Sie in der VergeOS-Oberfläche ausführen, wird direkt einer REST-API-Anfrage zugeordnet. Dies API-first-Design bedeutet, dass alles, worauf Sie im Dashboard klicken können – das Erstellen von VMs, das Konfigurieren von Netzwerken, das Verwalten von Mandanten – über HTTP-Endpunkte automatisiert werden kann. Dieser Abschnitt behandelt die drei primären Schnittstellen für den programmgesteuerten Zugriff: die REST-API selbst, das yb-api-Hilfsskript für die Automatisierung auf dem System selbst und die vrg-CLI für die Fernverwaltung.

Übersicht über die REST-API

Die VergeOS-API folgt den üblichen REST-Konventionen mit JSON-Nutzlasten und unterstützt den vollständigen Lebenszyklus jeder Ressource auf der Plattform.

HTTP-Methoden

Methode

Zweck

Beispiel

GET

Ressourcen abrufen

GET /api/v4/vms?fields=most

POST

Ressourcen erstellen oder Aktionen auslösen

POST /api/v4/vms

PUT

Vorhandene Ressourcen aktualisieren

PUT /api/v4/vms/36

DELETE

Ressourcen entfernen

DELETE /api/v4/vms/36

Abfrageparameter

Jede GET-Anfrage unterstützt OData-ähnliche Filterung und Feldauswahl:

Felder — Geben Sie an, welche Felder zurückgegeben werden sollen (z. B. fields=name,$key,ram oder fields=most für alle gängigen Felder)
filter — OData-ähnliche Filterausdrücke (z. B. filter=is_snapshot eq false)
sort — Ergebnisse nach Feld sortieren (z. B. sort=name)
limit / offset — Paginierungssteuerung für große Ergebnislisten

Datenformate

Alle API-Antworten werden im JSON-Format zurückgegeben. Die Request-Bodies für POST- und PUT-Operationen müssen ebenfalls JSON mit dem Content-Type: application/json Header sein.

Ratenbegrenzungen

Die API unterstützt maximal 1.000 Anfragen pro Stunde pro API-Schlüssel. Für Automatisierung mit hohem Volumen sollten Sie nach Möglichkeit Batch-Operationen verwenden und eine Wiederholungslogik mit exponentiellem Backoff implementieren.

Authentifizierung

VergeOS unterstützt zwei Authentifizierungsmethoden – Basic-HTTP-Authentifizierung und tokenbasierte Authentifizierung – jeweils für unterschiedliche Anwendungsfälle geeignet. Langzeitgültige API-Schlüssel sind eine Variante der Token-Methode und werden als Bearer-Token statt als Sitzungstoken übergeben:

1. Basic-HTTP-Authentifizierung

Die einfachste Methode – übergeben Sie die Anmeldedaten direkt mit jeder Anfrage. Der gesamte API-Verkehr erfordert HTTPS.

curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  --basic --user "admin:password" \
  -H "Accept: application/json"

2. Tokenbasierte Authentifizierung (Sitzungstoken)

Fordern Sie ein Sitzungstoken an, indem Sie Anmeldedaten per POST an /sys/tokenssenden. Verwenden Sie das zurückgegebene Token in nachfolgenden Anfragen über den x-yottabyte-token Header:

# Schritt 1: Ein Token abrufen
curl --basic \
  --data-ascii '{"login": "admin", "password": "secret"}' \
  --request "POST" \
  --header "Content-Type: application/json" \
  "https://vergeos.example.com/api/sys/tokens"

# Die Antwort enthält den Token-Schlüssel:
# {"location":"/sys/tokens/3a334...","$key":"3a334..."}

# Schritt 2: Das Token in nachfolgenden Anfragen verwenden
curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  -H "x-yottabyte-token: 3a334..." \
  -H "Accept: application/json"

# Schritt 3: Bei Bedarf abmelden
curl -X DELETE "https://vergeos.example.com/api/sys/tokens/3a334..."

Bearer-Token-Variante: Langzeitgültige API-Schlüssel

Für die Produktionsautomatisierung erstellen Sie persistente API-Schlüssel über System → Users → [User] → API Keys. Diese Schlüssel sind eine Bearer-Token-Variante der Token-Authentifizierung – sie funktionieren als Bearer-Tokens und bleiben bis zum Ablauf oder zur Löschung gültig:

curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  -H "Authorization: Bearer your-api-key-string" \
  -H "Content-Type: application/json"

API-Schlüssel unterstützen IP-Zulassungs-/Sperrlisten für die Sicherheit und konfigurierbare Ablaufdaten. Speichern Sie sie in Umgebungsvariablen statt sie fest zu codieren:

export VERGEOS_API_KEY="your-api-key-string"
curl -X GET "https://vergeos.example.com/api/v4/system" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"

API-Schlüssel werden nur einmal bei der Erstellung angezeigt. Wenn sie verloren gehen, müssen Sie den Schlüssel löschen und einen neuen erstellen.

API Explorer (Swagger)

VergeOS enthält eine integrierte Swagger-Dokumentationsseite die dynamisch aus dem laufenden System generiert wird und jede verfügbare Tabelle und Operation anzeigt.

So greifen Sie darauf zu:

Melden Sie sich in der VergeOS-Oberfläche an
Navigieren Sie zu System → API-Dokumentation
Durchsuchen Sie verfügbare Endpunkte, sehen Sie Schemata an und testen Sie API-Aufrufe direkt

Mit der Swagger-Oberfläche können Sie API-Aufrufe im Browser ausführen und den resultierenden curl Befehl, Antwortkörper und Header anzeigen – dadurch ist sie ein hervorragendes Werkzeug zum Prototyping von Automatisierungsskripten.

Wichtige API-Endpunkte

Die API organisiert Ressourcen in Tabellen. Hier sind die am häufigsten verwendeten Endpunkte:

Endpunkt

Zweck

/api/v4/vms

CRUD-Operationen für virtuelle Maschinen

/api/v4/vm_actions

VM-Energieoperationen, Klonen, Snapshot

/api/v4/machine_drives

VM-Speicherlaufwerke anhängen/verwalten

/api/v4/machine_nics

VM-Netzwerkschnittstellen konfigurieren

/api/v4/machine_devices

GPU-/PCI-Geräte-Passthrough

/api/v4/machine_status/{id}

Laufzeit-Energiezustand und Status

/api/v4/vnets

Verwaltung virtueller Netzwerke

/api/v4/vnet_rules

Firewall- und NAT-Regeln

/api/v4/tenants

Mandantenverwaltung (VDC)

/api/v4/nodes

Informationen zum physischen Knoten

/api/v4/clusters

Cluster-Konfiguration

/api/sys/tokens

Verwaltung von Sitzungstokens

Schema-Introspektion

Hängen Sie /$table an einen beliebigen Endpunkt an, um dessen vollständiges Datenbankschema abzurufen, einschließlich aller verfügbaren Felder und Typen:

# Das VM-Tabellenschema abrufen
curl -X GET "https://vergeos.example.com/api/v4/vms/\$table" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"

API-Übersicht zum VM-Lebenszyklus

Der häufigste Automatisierungs-Workflow ist die Bereitstellung einer vollständigen VM über die API. Dieser vierstufige Prozess spiegelt wider, was die Oberfläche im Hintergrund tut:

Schritt 1: Die VM erstellen

curl -X POST "https://vergeos.example.com/api/v4/vms" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-server-01",
    "description": "Produktions-Webserver",
    "machine_type": "pc-q35-9.0",
    "cpu_cores": 4,
    "cpu_type": "Cascadelake-Server",
    "ram": 8192,
    "os_family": "linux",
    "boot_order": "cd",
    "uefi": true,
    "allow_hotplug": true
  }'

# Antwort: {"location":"/v4/vms/42","$key":"42"}

Schritt 2: Ein Speicherlaufwerk hinzufügen

curl -X POST "https://vergeos.example.com/api/v4/machine_drives" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": 42,
    "name": "boot-disk",
    "media": "disk",
    "interface": "virtio-scsi",
    "disksize": 107374182400,
    "preferred_tier": "1"
  }'

Schritt 3: Eine Netzwerkschnittstelle hinzufügen

curl -X POST "https://vergeos.example.com/api/v4/machine_nics" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": 42,
    "vnet": 6,
    "interface": "virtio"
  }'

Schritt 4: Einschalten

curl -X POST "https://vergeos.example.com/api/v4/vm_actions" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "vm": 42,
    "action": "poweron"
  }'

Weitere Aktionen

Sobald die VM existiert, können Sie erweiterte Operationen über denselben vm_actions Endpunkt auslösen:

# Eine VM klonen
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "clone", "params": {"name": "web-server-clone", "quiesce": "true"}}'

# Einen Snapshot erstellen
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "snapshot", "params": {"name": "pre-upgrade"}}'

# Graceful herunterfahren
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "poweroff"}'

yb-api-Hilfsskript

Das yb-api ist ein integrierter Kommandozeilen-Wrapper, der auf jedem VergeOS-Knoten per SSH verfügbar ist. Er vereinfacht API-Aufrufe, indem er Authentifizierung, Header, URL-Erstellung, Abfragecodierung und Upload-Verarbeitung für Sie übernimmt.

Grundsyntax

yb-api --get|--post|--put|--delete [Optionen] /v4/<endpoint>

Häufige Optionen

Schalter

Zweck

--get

Ressourcen abrufen

--post='JSON'

Eine Ressource mit JSON-Nutzlast erstellen

--put='JSON'

Eine Ressource mit JSON-Nutzlast aktualisieren

--delete

Eine Ressource löschen

--server=IP

Auf ein bestimmtes VergeOS-System zielen

--user=NAME

Als bestimmter Benutzer authentifizieren

--fields='...'

Zu übergebende Felder auswählen

--filter='...'

OData-Filterausdruck

Anwendungsbeispiele

# Alle VMs auflisten (ohne Snapshots) mit Status
yb-api --get --user=admin --server=10.0.0.100 \
  --fields='name,$key,ram,machine#status#status as machine_status' \
  --filter='is_snapshot eq false' /v4/vms

# Detaillierte VM-Informationen einschließlich Laufwerken und NICs abrufen
yb-api --get --fields='most,machine[most,drives[most],nics[most]]' /v4/vms/1

# Eine neue VM erstellen
yb-api --post='{"name":"api-vm","enabled":true,"os_family":"linux",
  "cpu_cores":4,"ram":"8192"}' --user=admin --server=10.0.0.100 /v4/vms

# Eine VM umbenennen
yb-api --put='{"name":"new-name"}' --user=admin --server=10.0.0.100 /v4/vms/1

# Eine VM einschalten
yb-api --post='{"vm":1, "action": "poweron"}' /v4/vm_actions

# Tabellenschema für VMs abrufen
yb-api --get '/v4/vms/$table'

Das yb-api ist ideal für schnelle Ad-hoc-Abfragen und Skripting direkt auf VergeOS-Knoten. Für die Fernautomatisierung von Arbeitsstationen aus verwenden Sie die vrg-CLI oder die Python-/PowerShell-SDKs.

vrg-CLI

Das vrg Befehlszeilentool bietet eine voll ausgestattete Schnittstelle für die Fernverwaltung von VergeOS, in Python erstellt, mit über 200 Befehlen für VMs, Netzwerke, Speicher, Mandanten und Systemadministration.

Installation

Die vrg-CLI wird über mehrere Kanäle verteilt — wählen Sie den, der zu Ihrer Umgebung passt. Keiner davon ist an ein Betriebssystem gebunden; pipx ist der empfohlene Weg auf jedem unterstützten OS.

# pipx (empfohlen — isolierte Python-Umgebung, alle OSes)
pipx install vrg

# pip (alle OSes)
pip install vrg

# uv (alle OSes)
uv tool install vrg

# Homebrew (alle OSes, auf denen Homebrew läuft)
brew install verge-io/tap/vrg

Eine eigenständige Binärdatei (kein Python erforderlich) wird ebenfalls veröffentlicht für Linux x86_64, macOS ARM64, und Windows x86_64 — nützlich für Windows-Hosts ohne Python-Toolchain.

Wichtige Funktionen

VM-Verwaltung

Virtuelle Maschinen mit einfachen Befehlen erstellen, auflisten, starten, stoppen, Snapshots erstellen, klonen und löschen.

Netzwerkoperationen

Virtuelle Netzwerke, Firewall-Regeln, DHCP-Einstellungen und VPN-Konfigurationen verwalten.

Speicherverwaltung

NAS-Volumes, CIFS-/NFS-Freigaben verwalten und vSAN-Tiers überwachen.

Mandantenverwaltung

Mandanten bereitstellen, Ressourcen zuweisen und Multi-Tenant-Umgebungen verwalten.

Die vrg-CLI umschließt dieselbe oben dokumentierte REST-API und bietet Tab-Vervollständigung, formatierten Output und eine ergonomischere Oberfläche für den täglichen Betrieb von Ihrem Arbeitsplatz aus.

API-Fehlerbehandlung

Wenn API-Aufrufe fehlschlagen, gibt VergeOS standardmäßige HTTP-Statuscodes mit beschreibenden JSON-Fehlerkörpern zurück:

Statuscode

Bedeutung

Häufige Ursache

401

Nicht autorisiert

Ungültige Anmeldedaten oder abgelaufenes Token

403

Verboten

Unzureichende Berechtigungen für die Operation

404

Nicht gefunden

Ressource existiert nicht oder ungültiger Endpunkt

409

Konflikt

Konflikt im Ressourcenstatus (z. B. VM läuft bereits)

422

Validierungsfehler

Ungültige Parameter oder fehlende erforderliche Felder

429

Ratenbegrenzung erreicht

Limit von 1.000 Anfragen/Stunde überschritten

500

Serverfehler

Interner Fehler — Systemprotokolle prüfen

Kommen Sie von VMware oder Nutanix?

VergeOS stellt eine einzige versionierte /api/v4/ Oberfläche für jede Operation bereit — die Oberfläche selbst ist nur ein Client dieser API. Der integrierte Swagger-Explorer wird dynamisch aus dem Live-Schema des laufenden Systems generiert, sodass die Dokumentation immer mit dem übereinstimmt, was die API aktuell akzeptiert.

Bewährte Methoden für die API-Automatisierung

Verwenden Sie API-Schlüssel für die Produktionsautomatisierung statt Sitzungstoken — sie laufen bei Inaktivität nicht ab
Wenden Sie IP-Einschränkungen an für API-Schlüssel an, um zu begrenzen, wo sie verwendet werden können
Bestimmte Felder auswählen (fields=name,$key,ram) statt fields=most um die Nutzlastgröße zu reduzieren
Paginierung implementieren mit limit und offset für große Ergebnislisten
Asynchrone Operationen behandeln — Aktionen wie Klonen und Snapshot werden sofort zurückgegeben; abfragen machine_status bis zum Abschluss
Anmeldedaten in Umgebungsvariablen speichern — Tokens niemals fest in Skripten hinterlegen
Schema-Introspektion verwenden (/$table), um verfügbare Felder vor dem Schreiben von Automatisierungen zu ermitteln

Wie geht es weiter

Jetzt, da Sie die rohe API verstanden haben, behandeln die folgenden Seiten höherstufige Werkzeuge, die diese API in sprachnative Schnittstellen einbetten:

Python SDK (pyvergeos) — Pythonischer, typannotierter Wrapper mit Ressourcenmanagern und OData-Filter-Builder
PowerShell-Modul (PSVergeOS) — über 200 Cmdlets mit Pipeline-Unterstützung für Windows-native Automatisierung

VorherigeÜberblick

NächsteLabor: Infrastrukturautomatisierung

Zuletzt aktualisiert vor 2 Monaten

War das hilfreich?