> 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/fr/integrations-et-api/go-sdk.md).

# SDK Go VergeOS (govergeos)

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

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

### Dans go.mod

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

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

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

### Clé API

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

### Variables d'environnement

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

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

### Options du client

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

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

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

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

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

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

{% tabs %}
{% tab title="Filtrage de base" %}

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

{% endtab %}

{% tab title="Options multiples" %}

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

{% endtab %}

{% tab title="Sélection des champs" %}

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

{% endtab %}
{% endtabs %}

### Opérations concurrentes

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

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

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

## Gestion des erreurs

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

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

{% hint style="info" %}
**Types d’erreur disponibles**
{% endhint %}

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

## 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](https://go.dev/doc/)
* [Documentation de l'API VergeOS](/knowledge-base/fr/automation-api/verge-api-guide.md)
* [SDK Python (pyvergeos)](/automate-protect-and-extend/fr/integrations-et-api/python-sdk.md) - Alternative Python
* [Fournisseur Terraform](/automate-protect-and-extend/fr/integrations-et-api/terraform-provider.md) - Infrastructure as 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/fr/integrations-et-api/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.