API REST y herramientas CLI

Domina la API REST de VergeOS, el script auxiliar yb-api y la CLI vrg para la gestión y automatización programática de la infraestructura.

Cada operación que realizas en la interfaz de VergeOS se asigna directamente a una llamada a la API REST. Esto diseño API-first significa que todo lo que puedes pulsar en el panel —crear VMs, configurar redes, gestionar inquilinos— puede automatizarse mediante endpoints HTTP. Esta sección cubre las tres interfaces principales para acceso programático: la API REST en sí misma, el script de ayuda yb-api para automatización en el nodo, y la CLI vrg para la gestión remota.

Resumen de la API REST

La API de VergeOS sigue las convenciones REST estándar con cargas JSON, y admite el ciclo de vida completo de cada recurso de la plataforma.

Métodos HTTP

Método	Propósito	Ejemplo
GET	Recuperar recursos	GET /api/v4/vms?fields=most
POST	Crear recursos o activar acciones	POST /api/v4/vms
PUT	Actualizar recursos existentes	PUT /api/v4/vms/36
DELETE	Eliminar recursos	DELETE /api/v4/vms/36

Parámetros de consulta

Cada solicitud GET admite filtrado y selección de campos al estilo OData:

• campos — Especifica qué campos devolver (por ejemplo, fields=name,$key,ram o fields=most para todos los campos comunes)
• filter — Expresiones de filtro al estilo OData (por ejemplo, filter=is_snapshot eq false)
• sort — Ordena los resultados por campo (por ejemplo, sort=name)
• limit / offset — Controles de paginación para conjuntos de resultados grandes

Formatos de datos

Todas las respuestas de la API se devuelven en formato JSON. Los cuerpos de las solicitudes para las operaciones POST y PUT también deben ser JSON con la cabecera Content-Type: application/json .

Límites de tasa

La API admite un máximo de 1.000 solicitudes por hora por clave de API. Para automatizaciones de alto volumen, agrupa las operaciones cuando sea posible e implementa lógica de reintento con retroceso exponencial.

Autenticación

VergeOS admite dos métodos de autenticación —autenticación HTTP básica y autenticación basada en token—, cada uno adecuado para distintos casos de uso. Las claves de API de larga duración son una variante del método por token, presentada como un token Bearer en lugar de un token de sesión:

1. Autenticación HTTP básica

El método más simple: pasa las credenciales directamente con cada solicitud. Todo el tráfico de la API requiere HTTPS.

curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  --basic --user "admin:password" \
  -H "Accept: application/json"

2. Autenticación basada en token (tokens de sesión)

Solicita un token de sesión enviando por POST las credenciales a /sys/tokens. Usa el token devuelto en las solicitudes posteriores mediante la x-yottabyte-token cabecera:

# Paso 1: Obtener un token
curl --basic \
  --data-ascii '{"login": "admin", "password": "secret"}' \
  --request "POST" \
  --header "Content-Type: application/json" \
  "https://vergeos.example.com/api/sys/tokens"

# La respuesta incluye la clave del token:
# {"location":"/sys/tokens/3a334...","$key":"3a334..."}

# Paso 2: Usar el token en solicitudes posteriores
curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  -H "x-yottabyte-token: 3a334..." \
  -H "Accept: application/json"

# Paso 3: Cerrar sesión al terminar
curl -X DELETE "https://vergeos.example.com/api/sys/tokens/3a334..."

Variante de token Bearer: claves de API de larga duración

Para la automatización en producción, crea claves de API persistentes mediante Sistema → Usuarios → [Usuario] → Claves de API. Estas claves son una variante del token Bearer para la autenticación por token: funcionan como tokens Bearer y permanecen válidas hasta su expiración o eliminación:

curl -X GET "https://vergeos.example.com/api/v4/vms?fields=most" \
  -H "Authorization: Bearer your-api-key-string" \
  -H "Content-Type: application/json"

Las claves de API admiten listas de IP permitidas/bloqueadas por seguridad y fechas de caducidad. Guárdalas en variables de entorno en lugar de codificarlas directamente:

export VERGEOS_API_KEY="your-api-key-string"
curl -X GET "https://vergeos.example.com/api/v4/system" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"

Las claves de API solo se muestran una vez al crearse. Si se pierden, debes eliminar la clave y crear una nueva.

Explorador de API (Swagger)

VergeOS incluye una página de documentación Swagger integrada que se genera dinámicamente a partir del sistema en ejecución, mostrando todas las tablas y operaciones disponibles.

Para acceder a ella:

1. Inicia sesión en la interfaz de VergeOS
2. Vaya a Sistema → Documentación de la API
3. Explora los endpoints disponibles, consulta esquemas y prueba llamadas a la API directamente

La interfaz de Swagger te permite ejecutar llamadas a la API en el navegador y ver el curl comando, el cuerpo de la respuesta y las cabeceras resultantes, lo que la convierte en una excelente herramienta para prototipar scripts de automatización.

Endpoints clave de la API

La API organiza los recursos en tablas. Estos son los endpoints más utilizados:

Endpoint	Propósito
/api/v4/vms	Operaciones CRUD de máquinas virtuales
/api/v4/vm_actions	Operaciones de energía de VM, clonación, instantánea
/api/v4/machine_drives	Adjuntar/gestionar unidades de almacenamiento de la VM
/api/v4/machine_nics	Configurar interfaces de red de la VM
/api/v4/machine_devices	Passthrough de dispositivos GPU/PCI
/api/v4/machine_status/{id}	Estado de energía y estado de ejecución
/api/v4/vnets	Gestión de redes virtuales
/api/v4/vnet_rules	Reglas de firewall y NAT
/api/v4/tenants	Gestión de inquilinos (VDC)
/api/v4/nodes	Información de nodos físicos
/api/v4/clusters	Configuración del clúster
/api/sys/tokens	Gestión de tokens de sesión

Introspección del esquema

Añade /$table a cualquier endpoint para recuperar su esquema completo de base de datos, incluidos todos los campos y tipos disponibles:

# Obtener el esquema de la tabla de VMs
curl -X GET "https://vergeos.example.com/api/v4/vms/\$table" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}"

Recorrido por la API del ciclo de vida de una VM

El flujo de automatización más común es aprovisionar una VM completa mediante la API. Este proceso de cuatro pasos refleja lo que hace la interfaz de usuario por detrás:

Paso 1: Crear la VM

curl -X POST "https://vergeos.example.com/api/v4/vms" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-server-01",
    "description": "Servidor web de producción",
    "machine_type": "pc-q35-9.0",
    "cpu_cores": 4,
    "cpu_type": "Cascadelake-Server",
    "ram": 8192,
    "os_family": "linux",
    "boot_order": "cd",
    "uefi": true,
    "allow_hotplug": true
  }'

# Respuesta: {"location":"/v4/vms/42","$key":"42"}

Paso 2: Añadir una unidad de almacenamiento

curl -X POST "https://vergeos.example.com/api/v4/machine_drives" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": 42,
    "name": "boot-disk",
    "media": "disk",
    "interface": "virtio-scsi",
    "disksize": 107374182400,
    "preferred_tier": "1"
  }'

Paso 3: Añadir una interfaz de red

curl -X POST "https://vergeos.example.com/api/v4/machine_nics" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "machine": 42,
    "vnet": 6,
    "interface": "virtio"
  }'

Paso 4: Encender

curl -X POST "https://vergeos.example.com/api/v4/vm_actions" \
  -H "Authorization: Bearer ${VERGEOS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "vm": 42,
    "action": "poweron"
  }'

Acciones adicionales

Una vez que la VM existe, puedes activar operaciones avanzadas mediante el mismo vm_actions endpoint:

# Clonar una VM
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "clone", "params": {"name": "web-server-clone", "quiesce": "true"}}'

# Tomar una instantánea
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "snapshot", "params": {"name": "pre-upgrade"}}'

# Apagar de forma controlada
curl -X POST ".../api/v4/vm_actions" \
  -d '{"vm": 42, "action": "poweroff"}'

Script de ayuda yb-api

La yb-api es un contenedor de línea de comandos integrado disponible en cada nodo VergeOS mediante SSH. Simplifica las llamadas a la API gestionando por ti la autenticación, las cabeceras, la construcción de URL, la codificación de consultas y el manejo de cargas.

Sintaxis básica

yb-api --get|--post|--put|--delete [options] /v4/<endpoint>

Opciones comunes

Bandera	Propósito
--get	Recuperar recursos
--post='JSON'	Crear un recurso con una carga JSON
--put='JSON'	Actualizar un recurso con una carga JSON
--delete	Eliminar un recurso
--server=IP	Apuntar a un sistema VergeOS específico
--user=NOMBRE	Autenticarse como un usuario específico
--fields='...'	Seleccionar campos a devolver
--filter='...'	Expresión de filtro OData

Ejemplos de uso

# Listar todas las VMs (excluyendo instantáneas) con estado
yb-api --get --user=admin --server=10.0.0.100 \
  --fields='name,$key,ram,machine#status#status as machine_status' \
  --filter='is_snapshot eq false' /v4/vms

# Obtener información detallada de la VM, incluidas unidades y NICs
yb-api --get --fields='most,machine[most,drives[most],nics[most]]' /v4/vms/1

# Crear una nueva VM
yb-api --post='{"name":"api-vm","enabled":true,"os_family":"linux",
  "cpu_cores":4,"ram":"8192"}' --user=admin --server=10.0.0.100 /v4/vms

# Cambiar el nombre de una VM
yb-api --put='{"name":"new-name"}' --user=admin --server=10.0.0.100 /v4/vms/1

# Encender una VM
yb-api --post='{"vm":1, "action": "poweron"}' /v4/vm_actions

# Obtener el esquema de la tabla de VMs
yb-api --get '/v4/vms/$table'

La yb-api es ideal para consultas rápidas ad hoc y para programar directamente en nodos VergeOS. Para automatización remota desde estaciones de trabajo, usa la CLI vrg o los SDK de Python/PowerShell.

CLI vrg

La vrg la herramienta de línea de comandos proporciona una interfaz completa de gestión remota para VergeOS, creada en Python con más de 200 comandos que abarcan VMs, redes, almacenamiento, inquilinos y administración del sistema.

Instalación

La CLI vrg se distribuye a través de varios canales: elige el que mejor se adapte a tu entorno. Ninguno está restringido por sistema operativo; pipx es la ruta recomendada en todos los sistemas operativos compatibles.

# pipx (recomendado: entorno Python aislado, todos los SO)
pipx install vrg

# pip (todos los SO)
pip install vrg

# uv (todos los SO)
uv tool install vrg

# Homebrew (todos los SO que ejecutan Homebrew)
brew install verge-io/tap/vrg

También se publica un binario independiente (no requiere Python) para Linux x86_64, macOS ARM64, y Windows x86_64 — útil para hosts Windows sin una cadena de herramientas de Python.

Capacidades clave

Gestión de VMs

Crea, lista, inicia, detén, toma instantáneas, clona y elimina máquinas virtuales con comandos sencillos.

Operaciones de red

Gestiona redes virtuales, reglas de firewall, ajustes de DHCP y configuraciones de VPN.

Control de almacenamiento

Administra volúmenes NAS, recursos compartidos CIFS/NFS y supervisa los niveles de vSAN.

Gestión de inquilinos

Aprovisiona inquilinos, asigna recursos y gestiona entornos multiinquilino.

La CLI vrg envuelve la misma API REST documentada arriba, proporcionando autocompletado, salida formateada y una interfaz más ergonómica para las operaciones diarias desde tu estación de trabajo.

Gestión de errores de la API

Cuando las llamadas a la API fallan, VergeOS devuelve códigos de estado HTTP estándar con cuerpos de error JSON descriptivos:

Código de estado	Significado	Causa común
401	No autorizado	Credenciales inválidas o token caducado
403	Prohibido	Permisos insuficientes para la operación
404	No encontrado	El recurso no existe o el endpoint no es válido
409	Conflicto	Conflicto de estado del recurso (por ejemplo, la VM ya está en ejecución)
422	Error de validación	Parámetros inválidos o campos obligatorios ausentes
429	Limitado por tasa	Se superó el límite de 1.000 solicitudes/hora
500	Error del servidor	Error interno — revisa los registros del sistema

¿Vienes de VMware o Nutanix?

VergeOS expone una única /api/v4/ superficie versionada para cada operación: la interfaz de usuario en sí misma es solo un cliente de esa API. El explorador Swagger integrado se genera dinámicamente a partir del esquema en vivo del sistema en ejecución, por lo que la documentación siempre coincide con lo que la API acepta en ese momento.

Mejores prácticas para la automatización de la API

1. Usa claves API para automatización en producción en lugar de tokens de sesión: no caducan por inactividad
2. Aplica restricciones de IP a las claves de API para limitar dónde pueden usarse
3. Selecciona campos específicos (fields=name,$key,ram) en lugar de fields=most para reducir el tamaño de la carga útil
4. Implementa paginación con limit y offset para conjuntos de resultados grandes
5. Gestiona operaciones asíncronas — acciones como clonar y tomar instantáneas devuelven la respuesta inmediatamente; consulta machine_status hasta que finalice
6. Guarda las credenciales en variables de entorno — nunca codifiques los tokens directamente en los scripts
7. Usa la introspección del esquema (/$table) para descubrir los campos disponibles antes de escribir automatizaciones

¿Qué sigue?

Ahora que entiendes la API en bruto, las páginas siguientes cubren herramientas de nivel superior que envuelven esta API en interfaces nativas del lenguaje:

• SDK de Python (pyvergeos) — envoltorio con anotaciones de tipo, estilo Python, con administradores de recursos y generador de filtros OData
• Módulo de PowerShell (PSVergeOS) — más de 200 cmdlets con soporte de canalización para automatización nativa en Windows