SDK de Python (pyvergeos)

Automatiza la infraestructura de VergeOS con el SDK de Python pyvergeos: ciclo de vida de VM, redes, multitenencia, almacenamiento y recuperación ante desastres desde scripts de Python.

La pyvergeos El SDK proporciona una interfaz de estilo Python, con anotaciones de tipo, para toda la API REST de VergeOS. En lugar de crear solicitudes HTTP en bruto, trabajas con gestores de recursos — client.vms, client.networks, client.tenants — que se asignan directamente a objetos de VergeOS. El SDK se encarga de la autenticación, la paginación, los reintentos y el sondeo de tareas asíncronas para que tus scripts de automatización se mantengan limpios y centrados en la lógica de negocio.

Requisitos e instalación

Requisitos previos:

• Python 3.9 o superior
• VergeOS 26.0 o superior
• Funciona en Windows, macOS y Linux

Instalar desde PyPI (recomendado):

pip install pyvergeos

O con uv (alternativa más rápida):

uv add pyvergeos

Desde el código fuente (desarrollo):

git clone https://github.com/verge-io/pyvergeos.git
cd pyvergeos
pip install .

Autenticación

El SDK admite tres métodos de autenticación, cada uno adecuado para distintos entornos.

Nombre de usuario y contraseña

La forma más simple para scripts interactivos y desarrollo:

from pyvergeos import VergeClient

client = VergeClient(
    host="192.168.1.100",
    username="admin",
    password="secret",
    verify_ssl=False  # Solo para certificados autofirmados
)

Token de API

Para automatización en producción cuando ya tienes una clave API generada previamente:

client = VergeClient(
    host="192.168.1.100",
    token="your-api-token"
)

Variables de entorno

La forma recomendada para producción — mantiene las credenciales fuera del código fuente:

export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret
export VERGE_VERIFY_SSL=false      # Opcional
export VERGE_TIMEOUT=30            # Opcional
export VERGE_RETRY_TOTAL=3         # Opcional
export VERGE_RETRY_BACKOFF=1       # Opcional

client = VergeClient.from_env()

Gestor de contexto

Usa siempre el gestor de contexto en el código de producción para garantizar que las conexiones se cierren correctamente, incluso cuando ocurran excepciones:

with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()
    for vm in vms:
        print(f"{vm.name}: {vm.ram} MB de RAM")
# La conexión se cierra automáticamente aquí

Gestores de recursos

Cada tipo de recurso de VergeOS se expone a través de un gestor de recursos en el objeto cliente. Cada gestor proporciona métodos coherentes list(), get(), create()y métodos de acción.

Máquinas virtuales

client.vms — Crea, configura, controla la energía, clona, toma instantáneas y administra discos/NICs para las VM.

Redes

client.networks — Redes virtuales, reglas de firewall, DHCP, DNS y control de energía de la red.

Inquilinos

client.tenants — Aprovisionamiento multi-tenant, aislamiento de recursos, instantáneas, bloques de almacenamiento y bloques de red.

NAS y almacenamiento

client.nas — Servicios NAS, volúmenes, comparticiones CIFS/NFS y sincronización de volúmenes.

Recuperación ante desastres

client.dr — Instantáneas en la nube, sincronización de sitios y flujos de recuperación.

Usuarios y grupos

client.users — Cuentas de usuario, grupos, permisos y gestión de claves API.

Tareas y monitorización

client.tasks — Seguimiento asíncrono de tareas, espera y tiempos de espera. También: alarmas y registros.

Sistema y GPU

client.clusters, client.nodes, client.gpu — Información de clústeres/nodos, niveles de almacenamiento y gestión de dispositivos GPU.

Tabla completa de recursos

Categoría	Recursos disponibles
Máquinas virtuales	VM, discos, NIC, instantáneas
Redes	Redes, reglas de firewall, DNS, DHCP, alias, hosts
VPN	Conexiones IPSec, interfaces WireGuard y peers
NAS/Almacenamiento	Servicios NAS, volúmenes, comparticiones CIFS/NFS, sincronizaciones de volúmenes
Inquilinos	Gestión de tenants, instantáneas, bloques de almacenamiento, bloques de red
Usuarios y grupos	Usuarios, grupos, permisos, claves API
Sistema	Clústeres, nodos, niveles de almacenamiento, certificados
Supervisión	Alarmas, registros, tareas
Copias de seguridad y recuperación ante desastres	Perfiles de instantáneas, instantáneas en la nube, sitios, sincronizaciones de sitios

Filtrado de recursos

El SDK ofrece tres enfoques para filtrar recursos, desde argumentos de palabra clave simples hasta un generador completo de filtros OData.

Argumentos de palabra clave

La forma más simple para filtros básicos: pasa directamente los nombres de los campos:

# Encontrar todas las VM Linux en ejecución
vms = client.vms.list(status="running", os_family="linux")

# Coincidencia con comodines
vms = client.vms.list(name="prod-*")

Cadenas de filtro OData

Para consultas complejas, pasa expresiones de filtro OData en bruto:

# Combinar condiciones con operadores
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")

Generador de filtros (API fluida)

Construye filtros programáticamente con seguridad de tipos y autocompletado:

from pyvergeos import Filter

# Encadenamiento fluido con métodos de operador
f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))

Operadores de filtro disponibles:

Método	Operador OData	Ejemplo
.eq()	eq	Filter().eq("status", "running")
.ne()	ne	Filter().ne("os_family", "windows")
.gt()	gt	Filter().gt("ram", 4096)
.lt()	lt	Filter().lt("cpu_cores", 8)
.ge()	ge	Filter().ge("ram", 2048)
.le()	le	Filter().le("ram", 8192)
.and_()	y	Encadena varias condiciones
.or_()	o	Combina condiciones alternativas

Gestión de tareas asíncronas

Muchas operaciones de VergeOS — instantáneas, clones, migraciones — se ejecutan asíncronamente y devuelven un ID de tarea de inmediato. El SDK proporciona un gestor de tareas para consultar la finalización:

# La instantánea devuelve una referencia de tarea
result = vm.snapshot(retention=86400, quiesce=True)

# Esperar a que la instantánea se complete (bloquea hasta 300 segundos)
task = client.tasks.wait(result["task"], timeout=300)
print(f"Instantánea completada: {task}")

Si la tarea no se completa dentro del tiempo de espera, se TaskTimeoutError lanza con la task_id propiedad para que puedas comprobar el estado más tarde:

from pyvergeos import TaskTimeoutError

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"La tarea {e.task_id} sigue en ejecución — compruébalo más tarde")

Manejo de errores

El SDK proporciona una jerarquía estructurada de excepciones para que puedas capturar modos de fallo específicos:

Excepción	Descripción
VergeError	Excepción base para todos los errores del SDK
AuthenticationError	Credenciales inválidas o token caducado
NotFoundError	El recurso solicitado no existe
ConflictError	Conflicto de estado del recurso (por ejemplo, la VM ya está en ejecución)
ValidationError	Valores de parámetros no válidos
TaskTimeoutError	La tarea no se completó dentro del tiempo de espera
TaskError	La tarea falló durante la ejecución

from pyvergeos import NotFoundError, AuthenticationError

try:
    vm = client.vms.get(name="nonexistent-vm")
except NotFoundError:
    print("VM no encontrada — comprueba el nombre")
except AuthenticationError:
    print("La autenticación falló — verifica las credenciales")

Configuración de reintentos

El SDK reintenta automáticamente los errores transitorios (HTTP 429, 500, 502, 503, 504) con retroceso exponencial:

client = VergeClient(
    host="192.168.1.100",
    token="api-token",
    retry_total=5,            # Máximo de intentos de reintento (predeterminado: 3)
    retry_backoff_factor=2,   # Multiplicador de retroceso (predeterminado: 1)
)

Establece retry_total=0 para desactivar por completo los reintentos en operaciones sensibles al tiempo.

Cambio de contexto de tenant

pyvergeos puede conectarse a contextos de tenant desde el sistema anfitrión, lo que permite scripts de automatización centralizados que gestionan recursos en varios tenants:

# Obtener un tenant desde el sistema anfitrión
tenant = client.tenants.get(name="customer-a")

# Conectarse al contexto del tenant
tenant_client = tenant.connect()

# Ahora administrar recursos DENTRO del tenant
tenant_vms = tenant_client.vms.list()
for vm in tenant_vms:
    print(f"VM del tenant: {vm.name}")

# Crear una red dentro del tenant
tenant_client.networks.create(
    name="tenant-app-net",
    network_address="10.50.1.0/24",
    ip_address="10.50.1.1",
    dhcp_enabled=True
)

Esto es especialmente valioso para MSPs y proveedores de servicios que necesitan automatizar el aprovisionamiento en docenas o cientos de entornos de tenant desde un único script.

Ejemplos prácticos

Gestión del ciclo de vida de las VM

with VergeClient.from_env() as client:
    # Crear una nueva VM
    vm = client.vms.create(
        name="web-server-01",
        ram=4096,
        cpu_cores=2,
        os_family="linux"
    )

    # Añadir una unidad de datos de 50 GB
    vm.drives.add(name="data", size=50 * 1024 * 1024 * 1024)

    # Conectar a una red
    network = client.networks.get(name="app-network")
    vm.nics.add(network=network.key)

    # Encender
    vm.power_on()
    print(f"La VM {vm.name} está en ejecución")

Red con reglas de firewall

with VergeClient.from_env() as client:
    # Crear una red
    network = client.networks.create(
        name="web-tier",
        network_address="10.20.1.0/24",
        ip_address="10.20.1.1",
        dhcp_enabled=True
    )
    network.power_on()

    # Agregar reglas de firewall
    network.rules.create(
        name="Permitir HTTPS",
        action="accept",
        protocol="tcp",
        dest_port=443
    )
    network.rules.create(
        name="Permitir SSH",
        action="accept",
        protocol="tcp",
        dest_port=22
    )
    network.apply_rules()

Operaciones masivas con filtrado

with VergeClient.from_env() as client:
    # Crear una instantánea de todas las VM de producción en ejecución
    prod_vms = client.vms.list(name="prod-*", status="running")

    for vm in prod_vms:
        result = vm.snapshot(retention=86400, quiesce=True)
        task = client.tasks.wait(result["task"], timeout=300)
        print(f"Se creó una instantánea de {vm.name}")

Informe de inventario multi-tenant

with VergeClient.from_env() as client:
    for tenant in client.tenants.list():
        tenant_client = tenant.connect()
        vms = tenant_client.vms.list()
        print(f"\n--- {tenant.name} ---")
        for vm in vms:
            print(f"  {vm.name}: {vm.ram} MB de RAM, {vm.cpu_cores} núcleos")

Notas importantes

Seguridad en subprocesos

El cliente pyvergeos no es seguro para subprocesos. Si necesitas operaciones concurrentes, crea instancias separadas de VergeClient para cada subproceso. Para cargas de trabajo verdaderamente paralelas, considera el govergeos SDK de Go, diseñado para su uso concurrente con goroutines.

¿Vienes de VMware o Nutanix?

pyvergeos expone tres patrones que conviene conocer de entrada:

• Filtrado — un Filter() fluido genera expresiones de estilo OData (.eq(), .gt(), .and_(), .or_()), o puedes pasar una cadena OData en bruto a list(filter=...).
• Sondeo de tareas — las operaciones asíncronas devuelven una referencia de tarea; client.tasks.wait(task_id, timeout=...) bloquea hasta completarse y lanza TaskTimeoutError si se agota el tiempo.
• Contexto de tenant — tenant.connect() devuelve un cliente con ámbito dentro del tenant, de modo que el mismo script pueda controlar el sistema anfitrión y cualquier tenant hijo sin volver a conectarse a otro extremo.

Recursos adicionales

• Repositorio de GitHub — Código fuente, incidencias y contribuciones
• Paquete de PyPI — Última versión e historial de versiones
• Documentación de la API de VergeOS