SDK de VergeOS para Python (pyvergeos)

pyvergeos es un SDK de Python para administrar VergeOS a través de la API REST, que proporciona una interfaz en Python y con anotaciones de tipos para automatizar VM, redes, almacenamiento, inquilinos y recuperación ante desastres.

Descripción general

pyvergeos es un SDK de Python para gestionar la infraestructura de VergeOS a través de la API REST. Proporciona una interfaz anotada de tipos y con estilo Python para automatizar el ciclo de vida de las VM, la red, el almacenamiento, las operaciones multiinquilino y los flujos de trabajo de recuperación ante desastres, lo que lo hace ideal para scripts de automatización, desarrollo de herramientas e integraciones.

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: Administración de volúmenes, recursos compartidos CIFS/NFS y sincronización
• Multitenencia: Aprovisionamiento de inquilinos con aislamiento de recursos
• Recuperación ante desastres: Instantáneas en la nube, sincronización de sitios y flujos de trabajo de recuperación
• Filtrado: Compatibilidad con filtros OData mediante una API fluida de construcción de filtros
• Anotaciones de tipos: Pistas de tipo completas para el autocompletado del IDE y el análisis estático
• Multiplataforma: Compatibilidad con Windows, macOS y Linux

Requisitos

• Python 3.9 o posterior
• VergeOS 26.0 o posterior

Instalación

Desde PyPI (recomendado)

pip install pyvergeos

Usando uv

uv add pyvergeos

Desde el código fuente

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

Autenticación

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

Nombre de usuario/contraseña

from pyvergeos import VergeClient

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

Verificación de certificado SSL

Establezca verify_ssl=False solo para entornos con certificados autofirmados. Para entornos de producción con certificados válidos, omita este parámetro o establézcalo en True.

Token de API

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

Variables de entorno

export VERGE_HOST=192.168.1.100
export VERGE_USERNAME=admin
export VERGE_PASSWORD=secret

client = VergeClient.from_env()

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.

Gestor de contexto

with VergeClient(host="192.168.1.100", token="api-token") as client:
    vms = client.vms.list()

Limpieza automática

Usar el gestor de contexto (with instrucción) garantiza que la conexión se cierre correctamente, incluso si ocurre una excepción.

Recursos disponibles

El SDK proporciona acceso a los siguientes recursos de VergeOS:

Categoría	Recursos
Máquinas virtuales	VM, discos, NIC, instantáneas
Redes	Redes, reglas, DNS, DHCP, alias, hosts
VPN	Conexiones IPSec, interfaces y pares de WireGuard
NAS/Almacenamiento	Servicios, volúmenes, recursos compartidos CIFS/NFS, sincronizaciones de volúmenes
Inquilinos	Administración de inquilinos, instantáneas, almacenamiento, bloques de red
Usuarios y grupos	Usuarios, grupos, permisos, claves API
Sistema	Clusters, nodos, niveles de almacenamiento, certificados
Monitorización	Alarmas, registros, tareas
Copia de seguridad y DR	Perfiles de instantáneas, instantáneas en la nube, sitios, sincronizaciones de sitios

Ejemplos de uso

Administración de máquinas virtuales

from pyvergeos import VergeClient

client = VergeClient(host="192.168.1.100", username="admin", password="secret")

# Listar todas las VM
for vm in client.vms.list():
    print(f"{vm.name}: {vm.ram}MB RAM, {vm.cpu_cores} cores")

# Obtener una VM específica
vm = client.vms.get(name="web-server")

# Crear una VM
new_vm = client.vms.create(
    name="test-vm",
    ram=2048,
    cpu_cores=2,
    os_family="linux"
)

# Operaciones de energía
vm.power_on()
vm.power_off()
vm.reset()

# Instantáneas
vm.snapshot(retention=86400, quiesce=True)

# Clonar una VM
clone = vm.clone(name="test-clone")

# Agregar discos y NIC
vm.drives.add(name="data", size=50*1024*1024*1024)
vm.nics.add(network=network.key)

client.disconnect()

Creación y administración de redes

# Crear una red virtual
network = client.networks.create(
    name="app-network",
    network_address="10.10.1.0/24",
    ip_address="10.10.1.1",
    dhcp_enabled=True
)

network.power_on()
network.apply_rules()

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

Recursos de filtrado

El SDK admite múltiples enfoques de filtrado:

Argumentos de palabra clave

# Simple y legible para filtros básicos
vms = client.vms.list(status="running", name="prod-*")

Cadena de filtro OData

# Sintaxis completa de filtro OData para consultas complejas
vms = client.vms.list(filter="os_family eq 'linux' and ram gt 2048")

Constructor de filtros

# API fluida para construir filtros programáticamente
from pyvergeos import Filter

f = Filter().eq("os_family", "linux").and_().gt("ram", 2048)
vms = client.vms.list(filter=str(f))

Espera de tareas

Muchas operaciones en VergeOS se ejecutan de forma asíncrona. Use el administrador de tareas para esperar a que finalicen:

result = vm.snapshot()
task = client.tasks.wait(result["task"], timeout=300)

Operaciones asíncronas

Operaciones como instantáneas, clones y migraciones devuelven inmediatamente un ID de tarea. Use client.tasks.wait() para bloquear hasta que la operación se complete.

Manejo de errores

El SDK proporciona tipos de excepción específicos para diferentes condiciones de error:

from pyvergeos import NotFoundError, AuthenticationError, TaskTimeoutError

try:
    vm = client.vms.get(name="nonexistent")
except NotFoundError:
    print("VM no encontrada")

try:
    task = client.tasks.wait(task_id, timeout=60)
except TaskTimeoutError as e:
    print(f"Task {e.task_id} timed out")

Tipos de excepción disponibles

Excepción	Descripción
VergeError	Excepción base para todos los errores del SDK
AuthenticationError	Credenciales no válidas o token expirado
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

Casos de uso comunes

• Automatización de infraestructura: Aprovisione VMs, redes y almacenamiento mediante programación
• Integración CI/CD: Cree y destruya entornos de prueba en los pipelines
• Monitorización e informes: Consulte el estado de los recursos y genere informes de inventario
• 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
• Paquete de PyPI

Soporte

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

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

Recursos adicionales

• Documentación de Python
• Documentación de la API de VergeOS
• Módulo de PowerShell PSVergeOS - alternativa de PowerShell
• Proveedor de Terraform - infraestructura como código