SDK de VergeOS para Go (govergeos)

govergeos es una biblioteca cliente de Go para administrar la infraestructura de VergeOS a través de la API REST, que proporciona interfaces seguras en cuanto a tipos para automatizar VM, redes, almacenamiento, inquilinos y recuperación ante desastres.

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

go get github.com/verge-io/govergeos

En go.mod

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

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

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.

Clave API

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

Variables de entorno

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

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.

Opciones del cliente

El cliente admite opciones de configuración adicionales:

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

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

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:

Filtrado básico

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

Múltiples opciones

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

Selección de campos

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

Operaciones concurrentes

El SDK es seguro para hilos y admite operaciones concurrentes usando 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("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()

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.

Manejo de errores

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

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

Tipos de error disponibles

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
• Documentación del paquete Go

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
• Documentación de la API de VergeOS
• SDK de Python (pyvergeos) - Alternativa de Python
• Proveedor de Terraform - infraestructura como código