SDK Go VergeOS (govergeos)

govergeos est une bibliothèque cliente Go pour gérer l’infrastructure VergeOS via l’API REST, fournissant des interfaces typées pour automatiser les VM, le réseau, le stockage, les locataires et la reprise après sinistre.

Vue d’ensemble

govergeos est une bibliothèque cliente Go pour la gestion de l’infrastructure VergeOS via l’API REST. Elle fournit une interface Go typée et idiomatique pour automatiser le cycle de vie des VM, le réseau, le stockage, les opérations multi-locataires et les workflows de reprise après sinistre, ce qui en fait un outil idéal pour créer des outils, des opérateurs et de l’automatisation d’infrastructure.

Fonctionnalités clés

• Gestion des VM: Création, configuration, contrôle d'alimentation, clonage et instantanés
• Réseautage avancé: Réseaux virtuels, règles de pare-feu, DHCP, DNS, VPN IPSec et WireGuard
• NAS et stockage: Gestion des volumes, partages CIFS/NFS, navigation asynchrone des volumes et synchronisation
• Multi-location: Provisionnement des locataires avec isolation des ressources et gestion des nœuds
• Reprise après sinistre: Instantanés cloud, synchronisation des sites et flux de récupération
• API typée: Interfaces Go complètes pour le mock, la prise en charge du contexte et les opérations concurrentes sûres pour les threads
• Aucune dépendance: Bibliothèque standard uniquement — aucune dépendance externe
• Multiplateforme: Prise en charge de Windows, macOS et Linux

Prérequis

• Go 1.21 ou version ultérieure
• VergeOS 26.0 ou version ultérieure

Installation

Utilisation de go get

go get github.com/verge-io/govergeos

Dans go.mod

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

Authentification

Le SDK prend en charge plusieurs méthodes d'authentification :

Nom d'utilisateur/mot de passe

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), // Pour les certificats auto-signés
)
if err != nil {
    log.Fatal(err)
}

Vérification du certificat SSL

Définissez WithInsecureTLS(true) uniquement pour les environnements avec des certificats auto-signés. Pour les environnements de production avec des certificats valides, omettez cette option.

Clé API

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

Variables d'environnement

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	Requis	Par défaut	Description
VERGEOS_HOST	Oui	—	URL de base (par exemple, https://vergeos.example.com)
VERGEOS_USERNAME	Non*	—	Nom d’utilisateur pour l’authentification de base
VERGEOS_PASSWORD	Non*	—	Mot de passe pour l’authentification de base
VERGEOS_API_KEY	Non*	—	Clé API pour l’authentification Bearer
VERGEOS_VERIFY_SSL	Non	true	Vérifier les certificats TLS
VERGEOS_TIMEOUT	Non	30	Délai d’attente de la requête en secondes

*L’un des éléments (USERNAME+PASSWORD) ou API_KEY est requis.

Recommandé pour la production

L'utilisation de variables d'environnement permet de garder les identifiants hors de votre code source et facilite l'utilisation d'identifiants différents selon les environnements.

Options du client

Le client prend en charge des options de configuration supplémentaires :

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),
)

Ressources disponibles

Le SDK donne accès aux ressources VergeOS suivantes :

Catégorie	Services
Machines virtuelles	VMs, VMDrives, VMNICs, VMSnapshots, VMDevices
Réseautage	Networks, VNetRules, VNetAddresses, VNetHosts, VNetDNSViews/Zones/Records
VPN	VNetIPSecs, VNetIPSecPhase1s/Phase2s, VNetWireGuards, VNetWireGuardPeers
NAS/Stockage	NASServices, Volumes, VolumeSnapshots, VolumeCIFSShares, VolumeNFSShares, VolumeSyncs
Locataires	Tenants, TenantNodes, TenantStorage, TenantSnapshots, TenantLayer2Networks
Utilisateurs et groupes	Users, Groups, Members, Permissions, UserAPIKeys
Système	Clusters, Nodes, Settings, System, Certificates
Surveillance	Alarmes, journaux, tâches, niveaux de stockage, niveaux de cluster
Sauvegarde et reprise après sinistre	SnapshotProfiles, CloudSnapshots, Sites, SiteSyncs
Automatisation	Files, CloudInitFiles, WebhookURLs, Webhooks
Organisation	Tags, TagCategories, TagMembers, ResourceGroups

Exemples d'utilisation

Gestion des machines virtuelles

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

    // Lister toutes les VM
    vms, err := client.VMs.List(ctx)
    if err != nil {
        log.Fatal(err)
    }
    for _, vm := range vms {
        fmt.Printf("%s : %d Mo de RAM, %d cœurs\n", vm.Name, vm.RAM, vm.CPUCores)
    }

    // Obtenir une VM spécifique
    vm, err := client.VMs.Get(ctx, 42)
    if err != nil {
        log.Fatal(err)
    }

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

    // Opérations d’alimentation (utilisez ID.Int() pour obtenir l’ID entier)
    _ = client.VMs.PowerOn(ctx, newVM.ID.Int())
    _ = client.VMs.PowerOff(ctx, newVM.ID.Int())
    _ = client.VMs.Reset(ctx, newVM.ID.Int())

    // Créer un instantané
    _ = client.VMs.Snapshot(ctx, newVM.ID.Int(), &vergeos.VMSnapshotOptions{
        Name: "pre-upgrade",
    })

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

Création et gestion des réseaux

ctx := context.Background()

// Créer un réseau virtuel
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)
}

// Activer le réseau
_ = client.Networks.PowerOn(ctx, network.ID.Int())

// Ajouter une règle de pare-feu
rule, err := client.VNetRules.Create(ctx, &vergeos.VNetRuleCreateRequest{
    VNet:             network.ID.Int(),
    Name:             "Allow SSH",
    Action:           vergeos.Ptr("accept"),
    Protocol:         vergeos.Ptr("tcp"),
    Direction:        vergeos.Ptr("incoming"),
    DestinationPorts: vergeos.Ptr("22"),
})
if err != nil {
    log.Fatal(err)
}

// Appliquer les règles
_ = client.Networks.ApplyRules(ctx, network.ID.Int())

Filtrage des ressources

Le SDK prend en charge un filtrage flexible avec les options de liste :

Filtrage de base

// Filtrer les VM par état d’alimentation (en cours d’exécution)
vms, err := client.VMs.List(ctx,
    vergeos.WithFilter("powerstate eq true"),
)

Options multiples

// Combiner le filtre, le tri et la pagination
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),
)

Sélection des champs

// Retourner uniquement des champs spécifiques (utilisez $key pour le champ d’ID)
vms, err := client.VMs.List(ctx,
    vergeos.WithFields("$key,name,powerstate,ram"),
)

Opérations concurrentes

Le SDK est sûr pour les threads et prend en charge les opérations concurrentes à l’aide de goroutines :

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("Erreur lors de la récupération de la VM %d : %v", vmID, err)
            return
        }
        status := "stopped"
        if vm.PowerState {
            status = "running"
        }
        fmt.Printf("VM : %s, alimentation : %s\n", vm.Name, status)
    }(id)
}
wg.Wait()

Annulation du contexte

Toutes les méthodes acceptent un context.Context, ce qui vous permet de définir des délais d’attente et de gérer l’annulation des opérations de longue durée.

Gestion des erreurs

Le SDK fournit des types d’erreur spécifiques pour différentes conditions d’erreur :

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

vm, err := client.VMs.Get(ctx, 999)
if err != nil {
    if vergeos.IsNotFoundError(err) {
        fmt.Println("VM introuvable")
    } else if vergeos.IsAuthError(err) {
        fmt.Println("Échec de l’authentification")
    } else if vergeos.IsValidationError(err) {
        fmt.Println("Paramètres de requête invalides")
    } else {
        fmt.Printf("Erreur inattendue : %v\n", err)
    }
}

Types d’erreur disponibles

Type d’erreur	Fonction d’aide	Description
APIError	—	Erreur de base pour toutes les erreurs d’API
AuthError	IsAuthError(err)	Identifiants invalides ou jeton expiré
NotFoundError	IsNotFoundError(err)	La ressource demandée n'existe pas
ValidationError	IsValidationError(err)	Valeurs de paramètre invalides
UnsupportedVersionError	IsUnsupportedVersionError(err)	Version de VergeOS non prise en charge

Cas d'utilisation courants

• Automatisation de l'infrastructure: Provisionner des VM, des réseaux et du stockage par programmation
• Opérateurs Kubernetes: Créez des contrôleurs personnalisés pour les ressources VergeOS
• Intégration CI/CD: Créer et détruire des environnements de test dans les pipelines
• Outils de surveillance: Interrogez l’état des ressources et créez des tableaux de bord personnalisés
• Automatisation des sauvegardes: Planifier et gérer les instantanés et les sauvegardes cloud
• Provisionnement multi-locataire: Automatiser la création des locataires et l'allocation des ressources

Documentation et ressources

Pour une documentation complète, y compris toutes les méthodes disponibles et des exemples d'utilisation détaillés, visitez le dépôt officiel :

• Dépôt GitHub
• Documentation du package Go

Support

Si vous rencontrez des problèmes ou avez des demandes de fonctionnalités, veuillez ouvrir un ticket sur le dépôt GitHub :

https://github.com/verge-io/govergeos/issues

Ressources supplémentaires

• Documentation Go
• Documentation de l'API VergeOS
• SDK Python (pyvergeos) - Alternative Python
• Fournisseur Terraform - Infrastructure as code