VergeOS Go SDK (govergeos)

govergeos ist eine Go-Clientbibliothek zur Verwaltung der VergeOS-Infrastruktur über die REST API und bietet typsichere Schnittstellen zur Automatisierung von VMs, Netzwerken, Speicher, Mandanten und Disaster Recovery.

Übersicht

govergeos ist eine Go-Clientbibliothek zur Verwaltung der VergeOS-Infrastruktur über die REST-API. Sie bietet eine typsichere, idiomatische Go-Schnittstelle zur Automatisierung des VM-Lebenszyklus, von Netzwerken, Speicher, Mandantenbetrieb und Disaster-Recovery-Workflows und ist damit ideal zum Erstellen von Tools, Operatoren und Infrastrukturautomatisierung.

Hauptmerkmale

• 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, asynchrones Durchsuchen von Volumes und Synchronisierung
• Multi-Tenancy: Mandantenbereitstellung mit Ressourcenisolierung und Knotenverwaltung
• Disaster Recovery: Cloud-Snapshots, Standort-Synchronisierung und Wiederherstellungs-Workflows
• Typsichere API: Vollständige Go-Interfaces für Mocking, Unterstützung für Context und threadsichere nebenläufige Operationen
• Keine Abhängigkeiten: Nur Standardbibliothek—keine externen Abhängigkeiten
• Plattformübergreifend: Unterstützung für Windows, macOS und Linux

Anforderungen

• Go 1.21 oder höher
• VergeOS 26.0 oder höher

Installation

Mit go get

go get github.com/verge-io/govergeos

In go.mod

require github.com/verge-io/govergeos v0.1.2

Authentifizierung

Das SDK unterstützt mehrere Authentifizierungsmethoden:

Benutzername/Passwort

import vergeos "github.com/verge-io/govergeos"

client, err := vergeos.NewClient(
    vergeos.WithBaseURL("https://192.168.1.100"),
    vergeos.WithCredentials("admin", "secret"),
    vergeos.WithInsecureTLS(true), // Für selbstsignierte Zertifikate
)
if err != nil {
    log.Fatal(err)
}

SSL-Zertifikatsprüfung

Setzen Sie WithInsecureTLS(true) nur für Umgebungen mit selbstsignierten Zertifikaten. In Produktionsumgebungen mit gültigen Zertifikaten lassen Sie diese Option weg.

API-Schlüssel

client, err := vergeos.NewClient(
    vergeos.WithBaseURL("https://192.168.1.100"),
    vergeos.WithAPIKey("your-api-key-token"),
)

Umgebungsvariablen

export VERGEOS_HOST=https://192.168.1.100
export VERGEOS_USERNAME=admin
export VERGEOS_PASSWORD=secret
export VERGEOS_VERIFY_SSL=false

client, err := vergeos.NewClient(vergeos.WithEnvConfig())

Variable	Erforderlich	Standard	Beschreibung
VERGEOS_HOST	Ja	—	Basis-URL (z. B., https://vergeos.example.com)
VERGEOS_USERNAME	Nein*	—	Benutzername für die Basis-Authentifizierung
VERGEOS_PASSWORD	Nein*	—	Passwort für die Basis-Authentifizierung
VERGEOS_API_KEY	Nein*	—	API-Schlüssel für Bearer-Authentifizierung
VERGEOS_VERIFY_SSL	Nein	true	TLS-Zertifikate überprüfen
Anforderungs-Timeout in Sekunden	Nein	30	Anforderungs-Timeout in Sekunden

*Entweder (USERNAME+PASSWORD) oder API_KEY ist erforderlich.

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.

Client-Optionen

Der Client unterstützt zusätzliche Konfigurationsoptionen:

client, err := vergeos.NewClient(
    vergeos.WithBaseURL("https://192.168.1.100"),
    vergeos.WithCredentials("admin", "secret"),
    vergeos.WithTimeout(60 * time.Second),
    vergeos.WithUserAgent("my-automation/1.0"),
    vergeos.WithHTTPClient(customHTTPClient),
)

Verfügbare Ressourcen

Das SDK bietet Zugriff auf die folgenden VergeOS-Ressourcen:

Kategorie	Dienste
Virtuelle Maschinen	VMs, VMDrives, VMNICs, VMSnapshots, VMDevices
Netzwerk	Networks, VNetRules, VNetAddresses, VNetHosts, VNetDNSViews/Zones/Records
VPN	VNetIPSecs, VNetIPSecPhase1s/Phase2s, VNetWireGuards, VNetWireGuardPeers
NAS/Speicher	NASServices, Volumes, VolumeSnapshots, VolumeCIFSShares, VolumeNFSShares, VolumeSyncs
Mandanten	Tenants, TenantNodes, TenantStorage, TenantSnapshots, TenantLayer2Networks
Benutzer & Gruppen	Users, Groups, Members, Permissions, UserAPIKeys
System	Clusters, Nodes, Settings, System, Certificates
Überwachung	Alarms, Logs, Tasks, StorageTiers, ClusterTiers
Sicherung & DR	SnapshotProfiles, CloudSnapshots, Sites, SiteSyncs
Automatisierung	Files, CloudInitFiles, WebhookURLs, Webhooks
Organization	Tags, TagCategories, TagMembers, ResourceGroups

Anwendungsbeispiele

Virtuelle Maschinen verwalten

import (
    "context"
    "fmt"
    "log"

    vergeos "github.com/verge-io/govergeos"
)

func main() {
    client, err := vergeos.NewClient(
        vergeos.WithBaseURL("https://192.168.1.100"),
        vergeos.WithCredentials("admin", "secret"),
        vergeos.WithInsecureTLS(true),
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()

    // Alle VMs auflisten
    vms, err := client.VMs.List(ctx)
    if err != nil {
        log.Fatal(err)
    }
    for _, vm := range vms {
        fmt.Printf("%s: %dMB RAM, %d Kerne\n", vm.Name, vm.RAM, vm.CPUCores)
    }

    // Eine bestimmte VM abrufen
    vm, err := client.VMs.Get(ctx, 42)
    if err != nil {
        log.Fatal(err)
    }

    // Eine VM erstellen
    newVM, err := client.VMs.Create(ctx, &vergeos.VMCreateRequest{
        Name:     "test-vm",
        RAM:      2048,
        CPUCores: 2,
        Cluster:  1,
    })
    if err != nil {
        log.Fatal(err)
    }

    // Energieoperationen (verwenden Sie ID.Int() für die ganzzahlige ID)
    _ = client.VMs.PowerOn(ctx, newVM.ID.Int())
    _ = client.VMs.PowerOff(ctx, newVM.ID.Int())
    _ = client.VMs.Reset(ctx, newVM.ID.Int())

    // Einen Snapshot erstellen
    _ = client.VMs.Snapshot(ctx, newVM.ID.Int(), &vergeos.VMSnapshotOptions{
        Name: "vor dem Upgrade",
    })

    // Eine VM klonen
    clone, _ := client.VMs.Clone(ctx, vm.ID.Int(), &vergeos.VMCloneOptions{
        Name: "test-clone",
    })
    fmt.Printf("Geklonte VM: %s\n", clone.Name)
}

Netzwerke erstellen und verwalten

ctx := context.Background()

// Ein virtuelles Netzwerk erstellen
network, err := client.Networks.Create(ctx, &vergeos.NetworkCreateRequest{
    Name:        "app-network",
    Network:     "10.10.1.0/24",
    IPAddress:   "10.10.1.1",
    DHCPEnabled: vergeos.Ptr(true),
    DHCPStart:   "10.10.1.100",
    DHCPStop:    "10.10.1.200",
})
if err != nil {
    log.Fatal(err)
}

// Das Netzwerk einschalten
_ = client.Networks.PowerOn(ctx, network.ID.Int())

// Eine Firewall-Regel hinzufügen
rule, err := client.VNetRules.Create(ctx, &vergeos.VNetRuleCreateRequest{
    VNet:             network.ID.Int(),
    Name:             "SSH erlauben",
    Action:           vergeos.Ptr("accept"),
    Protocol:         vergeos.Ptr("tcp"),
    Direction:        vergeos.Ptr("incoming"),
    DestinationPorts: vergeos.Ptr("22"),
})
if err != nil {
    log.Fatal(err)
}

// Die Regeln anwenden
_ = client.Networks.ApplyRules(ctx, network.ID.Int())

Ressourcen filtern

Das SDK unterstützt flexibles Filtern mit Listenoptionen:

Einfaches Filtern

// VMs nach Energiestatus filtern (laufend)
vms, err := client.VMs.List(ctx,
    vergeos.WithFilter("powerstate eq true"),
)

Mehrere Optionen

// Filter, Sortierung und Paginierung kombinieren
vms, err := client.VMs.List(ctx,
    vergeos.WithFilter("os_family eq 'linux' and ram gt 2048"),
    vergeos.WithSort("name"),
    vergeos.WithLimit(10),
    vergeos.WithOffset(0),
)

Feldauswahl

// Nur bestimmte Felder zurückgeben (verwenden Sie $key für das ID-Feld)
vms, err := client.VMs.List(ctx,
    vergeos.WithFields("$key,name,powerstate,ram"),
)

Nebenläufige Operationen

Das SDK ist threadsicher und unterstützt nebenläufige Operationen mit Goroutinen:

import "sync"

var wg sync.WaitGroup
vmIDs := []int{1, 2, 3, 4, 5}

for _, id := range vmIDs {
    wg.Add(1)
    go func(vmID int) {
        defer wg.Done()
        vm, err := client.VMs.Get(ctx, vmID)
        if err != nil {
            log.Printf("Fehler beim Abrufen von VM %d: %v", vmID, err)
            return
        }
        status := "gestoppt"
        if vm.PowerState {
            status = "laufend"
        }
        fmt.Printf("VM: %s, Energie: %s\n", vm.Name, status)
    }(id)
}
wg.Wait()

Kontextabbruch

Alle Methoden akzeptieren einen context.Context, wodurch Sie Timeouts setzen und Abbrüche für lang laufende Operationen behandeln können.

Fehlerbehandlung

Das SDK stellt für verschiedene Fehlerbedingungen spezielle Fehlertypen bereit:

import vergeos "github.com/verge-io/govergeos"

vm, err := client.VMs.Get(ctx, 999)
if err != nil {
    if vergeos.IsNotFoundError(err) {
        fmt.Println("VM nicht gefunden")
    } else if vergeos.IsAuthError(err) {
        fmt.Println("Authentifizierung fehlgeschlagen")
    } else if vergeos.IsValidationError(err) {
        fmt.Println("Ungültige Anforderungsparameter")
    } else {
        fmt.Printf("Unerwarteter Fehler: %v\n", err)
    }
}

Verfügbare Fehlertypen

Fehlertyp	Hilfsfunktion	Beschreibung
APIError	—	Basisfehler für alle API-Fehler
AuthError	IsAuthError(err)	Ungültige Anmeldedaten oder abgelaufener Token
NotFoundError	IsNotFoundError(err)	Angeforderte Ressource existiert nicht
ValidationError	IsValidationError(err)	Ungültige Parameterwerte
UnsupportedVersionError	IsUnsupportedVersionError(err)	VergeOS-Version nicht unterstützt

Häufige Anwendungsfälle

• Infrastrukturautomatisierung: VMs, Netzwerke und Speicher programmatisch bereitstellen
• Kubernetes-Operatoren: Eigene Controller für VergeOS-Ressourcen erstellen
• CI/CD-Integration: Testumgebungen in Pipelines erstellen und zerstören
• Überwachungstools: Ressourcenstatus abfragen und eigene Dashboards 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
• Go-Paketdokumentation

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/govergeos/issues

Weitere Ressourcen

• Go-Dokumentation
• VergeOS-API-Dokumentation
• Python SDK (pyvergeos) - Python-Alternative
• Terraform-Provider - Infrastruktur als Code