> 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/es/integraciones-y-api/go-sdk.md).

# SDK de VergeOS para Go (govergeos)

## Descripción general

govergeos es una biblioteca cliente de Go para gestionar la infraestructura de VergeOS a través de la API REST. Proporciona una interfaz de Go idiomática y con seguridad de tipos para automatizar el ciclo de vida de las VMs, redes, almacenamiento, operaciones multiinquilino y flujos de trabajo de recuperación ante desastres, lo que lo hace ideal para crear herramientas, operadores y automatización de infraestructura.

## Características clave

* **Gestión de VM**: Creación, configuración, control de energía, clonación e instantáneas
* **Redes avanzadas**: Redes virtuales, reglas de firewall, DHCP, DNS, VPN IPSec y WireGuard
* **NAS y almacenamiento**: Gestión de volúmenes, recursos compartidos CIFS/NFS, exploración asíncrona de volúmenes y sincronización
* **Multitenencia**: Aprovisionamiento de inquilinos con aislamiento de recursos y gestión de nodos
* **Recuperación ante desastres**: Instantáneas en la nube, sincronización de sitios y flujos de trabajo de recuperación
* **API con seguridad de tipos**: Interfaces completas de Go para simulación, soporte de contexto y operaciones concurrentes seguras para hilos
* **Sin dependencias**: Solo biblioteca estándar; sin dependencias externas
* **Multiplataforma**: Compatibilidad con Windows, macOS y Linux

## Requisitos

* Go 1.21 o posterior
* VergeOS 26.0 o posterior

## Instalación

### Usando go get

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

### En go.mod

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

## Autenticación

El SDK admite múltiples métodos de autenticación:

### Nombre de usuario/contraseña

```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), // Para certificados autofirmados
)
if err != nil {
    log.Fatal(err)
}
```

{% hint style="info" %}
**Verificación de certificado SSL**

Establezca `WithInsecureTLS(true)` solo para entornos con certificados autofirmados. Para entornos de producción con certificados válidos, omite esta opción.
{% endhint %}

### Clave API

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

### Variables de entorno

```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             | Requerido | Predeterminado | Descripción                                      |
| -------------------- | --------- | -------------- | ------------------------------------------------ |
| `VERGEOS_HOST`       | Sí        | —              | URL base (p. ej., `https://vergeos.example.com`) |
| `VERGEOS_USERNAME`   | No\*      | —              | Nombre de usuario para autenticación básica      |
| `VERGEOS_PASSWORD`   | No\*      | —              | Contraseña para autenticación básica             |
| `VERGEOS_API_KEY`    | No\*      | —              | Clave API para autenticación bearer              |
| `VERGEOS_VERIFY_SSL` | No        | `true`         | Verificar certificados TLS                       |
| `VERGEOS_TIMEOUT`    | No        | `30`           | Tiempo de espera de la solicitud en segundos     |

\*Se requiere una de las opciones (USERNAME+PASSWORD) o API\_KEY.

{% hint style="success" %}
**Recomendado para producción**

Usar variables de entorno mantiene las credenciales fuera de su código fuente y facilita el uso de diferentes credenciales en distintos entornos.
{% endhint %}

### Opciones del cliente

El cliente admite opciones de configuración adicionales:

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

## Recursos disponibles

El SDK proporciona acceso a los siguientes recursos de VergeOS:

| Categoría               | Servicios                                                                             |
| ----------------------- | ------------------------------------------------------------------------------------- |
| Máquinas virtuales      | VMs, VMDrives, VMNICs, VMSnapshots, VMDevices                                         |
| Redes                   | Networks, VNetRules, VNetAddresses, VNetHosts, VNetDNSViews/Zones/Records             |
| VPN                     | VNetIPSecs, VNetIPSecPhase1s/Phase2s, VNetWireGuards, VNetWireGuardPeers              |
| NAS/Almacenamiento      | NASServices, Volumes, VolumeSnapshots, VolumeCIFSShares, VolumeNFSShares, VolumeSyncs |
| Inquilinos              | Tenants, TenantNodes, TenantStorage, TenantSnapshots, TenantLayer2Networks            |
| Usuarios y grupos       | Users, Groups, Members, Permissions, UserAPIKeys                                      |
| Sistema                 | Clusters, Nodes, Settings, System, Certificates                                       |
| Monitorización          | Alarms, Logs, Tasks, StorageTiers, ClusterTiers                                       |
| Copia de seguridad y DR | SnapshotProfiles, CloudSnapshots, Sites, SiteSyncs                                    |
| Automatización          | Files, CloudInitFiles, WebhookURLs, Webhooks                                          |
| Organization            | Tags, TagCategories, TagMembers, ResourceGroups                                       |

## Ejemplos de uso

### Administración de máquinas virtuales

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

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

    // Obtener una VM específica
    vm, err := client.VMs.Get(ctx, 42)
    if err != nil {
        log.Fatal(err)
    }

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

    // Operaciones de energía (usa ID.Int() para obtener el ID entero)
    _ = client.VMs.PowerOn(ctx, newVM.ID.Int())
    _ = client.VMs.PowerOff(ctx, newVM.ID.Int())
    _ = client.VMs.Reset(ctx, newVM.ID.Int())

    // Crear una instantánea
    _ = client.VMs.Snapshot(ctx, newVM.ID.Int(), &vergeos.VMSnapshotOptions{
        Name: "pre-upgrade",
    })

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

### Creación y administración de redes

```go
ctx := context.Background()

// Crear una red virtual
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)
}

// Encender la red
_ = client.Networks.PowerOn(ctx, network.ID.Int())

// Añadir una regla de firewall
rule, err := client.VNetRules.Create(ctx, &vergeos.VNetRuleCreateRequest{
    VNet:             network.ID.Int(),
    Name:             "Permitir SSH",
    Action:           vergeos.Ptr("accept"),
    Protocol:         vergeos.Ptr("tcp"),
    Direction:        vergeos.Ptr("incoming"),
    DestinationPorts: vergeos.Ptr("22"),
})
if err != nil {
    log.Fatal(err)
}

// Aplicar las reglas
_ = client.Networks.ApplyRules(ctx, network.ID.Int())
```

### Recursos de filtrado

El SDK admite un filtrado flexible con opciones de lista:

{% tabs %}
{% tab title="Filtrado básico" %}

```go
// Filtrar VMs por estado de energía (en ejecución)
vms, err := client.VMs.List(ctx,
    vergeos.WithFilter("powerstate eq true"),
)
```

{% endtab %}

{% tab title="Múltiples opciones" %}

```go
// Combinar filtro, ordenación y paginación
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="Selección de campos" %}

```go
// Devolver solo campos específicos (usa $key para el campo ID)
vms, err := client.VMs.List(ctx,
    vergeos.WithFields("$key,name,powerstate,ram"),
)
```

{% endtab %}
{% endtabs %}

### Operaciones concurrentes

El SDK es seguro para hilos y admite operaciones concurrentes usando 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("Error al obtener la VM %d: %v", vmID, err)
            return
        }
        status := "detenida"
        if vm.PowerState {
            status = "en ejecución"
        }
        fmt.Printf("VM: %s, Energía: %s\n", vm.Name, status)
    }(id)
}
wg.Wait()
```

{% hint style="success" %}
**Cancelación de contexto**

Todos los métodos aceptan un `context.Context`, lo que te permite establecer tiempos de espera y gestionar la cancelación de operaciones de larga duración.
{% endhint %}

## Manejo de errores

El SDK proporciona tipos de error específicos para distintas condiciones de error:

```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 no encontrada")
    } else if vergeos.IsAuthError(err) {
        fmt.Println("Autenticación fallida")
    } else if vergeos.IsValidationError(err) {
        fmt.Println("Parámetros de solicitud no válidos")
    } else {
        fmt.Printf("Error inesperado: %v\n", err)
    }
}
```

{% hint style="info" %}
**Tipos de error disponibles**
{% endhint %}

| Tipo de error             | Función auxiliar                 | Descripción                              |
| ------------------------- | -------------------------------- | ---------------------------------------- |
| `APIError`                | —                                | Error base para todos los errores de API |
| `AuthError`               | `IsAuthError(err)`               | Credenciales no válidas o token expirado |
| `NotFoundError`           | `IsNotFoundError(err)`           | El recurso solicitado no existe          |
| `ValidationError`         | `IsValidationError(err)`         | Valores de parámetros no válidos         |
| `UnsupportedVersionError` | `IsUnsupportedVersionError(err)` | Versión de VergeOS no compatible         |

## Casos de uso comunes

* **Automatización de infraestructura**: Aprovisione VMs, redes y almacenamiento mediante programación
* **Operadores de Kubernetes**: Crear controladores personalizados para recursos de VergeOS
* **Integración CI/CD**: Cree y destruya entornos de prueba en los pipelines
* **Herramientas de monitoreo**: Consultar el estado de los recursos y crear paneles personalizados
* **Automatización de copias de seguridad**: Programe y administre instantáneas y copias de seguridad en la nube
* **Aprovisionamiento multitenencia**: Automatice la creación de inquilinos y la asignación de recursos

## Documentación y recursos

Para obtener la documentación completa, incluidos todos los métodos disponibles y ejemplos de uso detallados, visite el repositorio oficial:

* [Repositorio de GitHub](https://github.com/verge-io/govergeos)
* [Documentación del paquete Go](https://pkg.go.dev/github.com/verge-io/govergeos)

## Soporte

Si encuentra problemas o tiene solicitudes de funciones, abra un issue en el repositorio de GitHub:

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

## Recursos adicionales

* [Documentación de Go](https://go.dev/doc/)
* [Documentación de la API de VergeOS](/knowledge-base/es/automation-api/verge-api-guide.md)
* [SDK de Python (pyvergeos)](/automate-protect-and-extend/es/integraciones-y-api/python-sdk.md) - Alternativa de Python
* [Proveedor de Terraform](/automate-protect-and-extend/es/integraciones-y-api/terraform-provider.md) - infraestructura como código


---

# 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/es/integraciones-y-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.