> 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/go-sdk.md).

# VergeOS Go SDK (govergeos)

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

```bash
go get github.com/verge-io/govergeos
```

### In go.mod

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

## Authentifizierung

Das SDK unterstützt mehrere Authentifizierungsmethoden:

### Benutzername/Passwort

```go
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)
}
```

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

### API-Schlüssel

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

### Umgebungsvariablen

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

```go
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.

{% 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 %}

### Client-Optionen

Der Client unterstützt zusätzliche Konfigurationsoptionen:

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

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

```go
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:

{% tabs %}
{% tab title="Einfaches Filtern" %}

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

{% endtab %}

{% tab title="Mehrere Optionen" %}

```go
// 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),
)
```

{% endtab %}

{% tab title="Feldauswahl" %}

```go
// 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"),
)
```

{% endtab %}
{% endtabs %}

### Nebenläufige Operationen

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

```go
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()
```

{% hint style="success" %}
**Kontextabbruch**

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

## Fehlerbehandlung

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

```go
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)
    }
}
```

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

| 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](https://github.com/verge-io/govergeos)
* [Go-Paketdokumentation](https://pkg.go.dev/github.com/verge-io/govergeos)

## 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](https://go.dev/doc/)
* [VergeOS-API-Dokumentation](/knowledge-base/de/automation-api/verge-api-guide.md)
* [Python SDK (pyvergeos)](/automate-protect-and-extend/de/integrationen-und-apis/python-sdk.md) - Python-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/go-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.