API de gestión de energía de VM

Guía completa para gestionar los estados de energía de las VM en VergeOS, incluidos iniciar, detener, reiniciar y supervisar el estado de energía

Puntos clave

• Controla los estados de energía de la VM mediante puntos finales de la API REST
• Compatibilidad con operaciones de energía graduales y forzadas
• Supervisa el estado de energía y el estado de ejecución de la VM
• Comprende la clave de VM frente a la clave de Machine para diferentes comprobaciones de estado

Esta guía cubre la administración de los estados de energía de las máquinas virtuales en VergeOS, incluyendo el inicio, la detención, el reinicio y la supervisión de las VMs. La API de VergeOS proporciona capacidades integrales de administración de energía con operaciones tanto graduales como forzadas.

Etapa: Administración de energía de VM (2 de 4) Entrada: clave de VM (42) desde la creación, tipo de operación de energía Salida: cambios de estado de energía, estado de ejecución Anterior: VM creada → Creación de VM Siguientes pasos comunes:

• Configurar ajustes de la VM → Configuración de la VM
• Operaciones avanzadas → Operaciones avanzadas de VM

Este documento ayuda con

• "Cómo iniciar/detener VMs vía API"
• "Comprobando el estado de energía de la VM"
• "Apagado gradual vs forzado de la VM"
• "Operaciones de reinicio y restablecimiento de la VM"
• "Supervisión del estado de energía de la VM"
• "Automatización de la gestión de energía"
• "Solución de problemas de inicio de la VM"
• "Operaciones de energía programadas"
• "Optimización de recursos mediante el control de energía"

Referencia rápida

Puntos finales principales

• Acciones de energía: POST /api/v4/vm_actions
• Estado de la VM: GET /api/v4/vms/{id}
• Estado de energía: GET /api/v4/machine_status/{machine_id}

Acciones clave

• poweron: Iniciar VM
• poweroff: Apagado gradual (ACPI)
• kill: Apagado forzado
• reset: Reiniciar VM

Autenticación

-H "Authorization: Bearer YOUR_API_KEY"
-H "Content-Type: application/json"

Requisitos previos

La VM debe crearse primero → Ver Creación de VM

Referencia rápida de la API

Operación	Método	Punto final	Tipo de clave	Propósito
Encendido	POST	/api/v4/vm_actions	clave de VM	Iniciar máquina virtual
Apagar	POST	/api/v4/vm_actions	clave de VM	Apagado gradual (ACPI)
Apagado forzado	POST	/api/v4/vm_actions	clave de VM	Terminación inmediata
Reinicie	POST	/api/v4/vm_actions	clave de VM	Reiniciar VM
Información de la VM	GET	/api/v4/vms/{id}	clave de VM	Datos de configuración
Estado de energía	GET	/api/v4/machine_status/{id}	Clave de máquina	Estado de ejecución

Índice de resolución de problemas

• 409 Conflicto: VM ya en ejecución, VM no en ejecución, desajuste del estado de energía
• 507 Recursos insuficientes: Recursos del clúster insuficientes, memoria/CPU no disponibles
• 403 Prohibido: Permisos de la clave API, acceso al clúster denegado, acceso a la VM restringido
• 404 No encontrado: Clave de VM no válida, VM eliminada, clave de máquina no encontrada
• 408 Tiempo de espera de la solicitud: Tiempo de espera agotado en la operación de energía, VM no responde, fallo de comunicación con el clúster
• 500 Error interno del servidor: Problemas del hipervisor, problemas del nodo, fallos de almacenamiento

Iniciando VMs

POST /api/v4/vm_actions

Descripción: Enciende una máquina virtual y espera a que alcance el estado en ejecución.

Solicitud de encendido:

{
  "action": "poweron",
  "params": {},
  "vm": "42"
}

Llamada API completa:

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

Respuesta: 201 Creado cuando se inicia la acción.

Mejores prácticas

• Verifica siempre la configuración de la VM antes de encenderla
• Asegúrate de que todos los discos y interfaces de red requeridos estén conectados
• Comprueba la disponibilidad de recursos del clúster
• Verifica que la VM no esté ya en ejecución para evitar conflictos

Deteniendo VMs

Apagado gradual (ACPI)

Descripción: Envía una señal de apagado ACPI al sistema operativo invitado, permitiéndole apagarse correctamente.

{
  "action": "poweroff",
  "vm": "42"
}

Llamada API completa:

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

Apagado forzado (Kill)

Descripción: Termina inmediatamente la VM sin permitir que el SO invitado se apague correctamente. Úsalo solo cuando falle el apagado gradual.

{
  "action": "kill",
  "vm": "42"
}

Llamada API completa:

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

Apagado forzado

Usando kill esta acción puede causar pérdida o corrupción de datos. Intenta siempre el apagado gradual poweroff primero y usa solo kill cuando sea necesario.

Reiniciando VMs

Reinicio gradual (ACPI)

Descripción: Envía una señal de reinicio ACPI al sistema operativo invitado para un reinicio limpio.

{
  "action": "reset",
  "params": {
    "graceful": true
  },
  "vm": "42"
}

Llamada API completa:

curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "action": "reset",
    "params": {
      "graceful": true
    },
    "vm": "42"
  }'

Restablecimiento duro (ciclo de energía)

Descripción: Reinicia inmediatamente la VM sin permitir que el SO invitado se apague correctamente.

{
  "action": "reset",
  "vm": "42"
}

Llamada API completa:

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

Estado e información de la VM

GET /api/v4/vms/{id}

Descripción: Recupera la configuración y los metadatos de la VM usando varios filtros de campos.

Obtener información completa de la VM:

curl "https://your-vergeos.example.com/api/v4/vms/42?fields=most" \\
  -H "Authorization: Bearer YOUR_API_KEY"

Ejemplo de respuesta:

{
  "$key": 42,
  "name": "test",
  "machine": 54,
  "description": "VM de prueba",
  "enabled": true,
  "created": 1755991665,
  "modified": 1755993248,
  "is_snapshot": false,
  "machine_type": "pc-q35-9.0",
  "allow_hotplug": true,
  "guest_agent": true,
  "cpu_cores": 3,
  "cpu_type": "host",
  "ram": 16384,
  "console": "spice",
  "video": "qxl",
  "sound": "none",
  "os_family": "linux",
  "rtc_base": "utc",
  "boot_order": "cd",
  "console_pass_enabled": false,
  "usb_tablet": true,
  "uefi": true,
  "secure_boot": false,
  "serial_port": false,
  "boot_delay": 5,
  "uuid": "821e96ec-2479-7cc4-7c14-c623557bdd2b",
  "need_restart": false,
  "console_status": 42,
  "cloudinit_datasource": "none",
  "imported": false,
  "created_from": "custom",
  "migration_method": "auto",
  "note": "Esta es una VM de prueba",
  "power_cycle_timeout": 0,
  "allow_export": true,
  "creator": "admin",
  "nested_virtualization": true,
  "disable_hypervisor": true,
  "usb_legacy": false
}

Estado de energía y estado de ejecución de la VM

GET /api/v4/machine_status/{machine_id}

Descripción: Recupera el estado real de ejecución y el estado de energía de una VM usando la clave de máquina.

Comprobar el estado de energía de la VM:

curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=most" \\
  -H "Authorization: Bearer YOUR_API_KEY"

Ejemplo de respuesta de VM detenida

{
  "$key": 54,
  "machine": 54,
  "running": false,
  "migratable": true,
  "node": null,
  "migrated_node": null,
  "migration_destination": null,
  "started": 1755993338,
  "local_time": 0,
  "status": "stopped",
  "status_info": "",
  "state": "offline",
  "powerstate": false,
  "last_update": 1755993358,
  "running_cores": 3,
  "running_ram": 16384,
  "agent_version": "",
  "agent_features": [],
  "agent_guest_info": []
}

Ejemplo de respuesta de VM en ejecución

{
  "$key": 44,
  "machine": 44,
  "running": true,
  "migratable": true,
  "node": 3,
  "migrated_node": null,
  "migration_destination": null,
  "started": 1755460982,
  "local_time": 0,
  "status": "running",
  "status_info": "",
  "state": "online",
  "powerstate": true,
  "last_update": 1755993927,
  "running_cores": 6,
  "running_ram": 12288,
  "agent_version": "",
  "agent_features": [],
  "agent_guest_info": []
}

Estado de la VM frente al estado de la máquina

• Información de la VM (/api/v4/vms/{vm_key}): Configuración, ajustes y metadatos
• Estado de energía (/api/v4/machine_status/{machine_key}): Estado de ejecución, estado de energía y uso de recursos
• Usa siempre la clave de máquina (no la clave de VM) para comprobar el estado real de energía y el estado de ejecución

Campos de estado

• powerstate: Booleano que indica si la VM está encendida
• running: Booleano que indica si la VM se está ejecutando actualmente
• status: Estado de texto ("running", "stopped", etc.)
• state: Estado general ("online", "offline")
• node: En qué nodo físico se está ejecutando la VM (null si está detenida)

Supervisión del estado de energía

Comprobación solo del estado de energía

Para comprobaciones rápidas del estado de energía, puedes solicitar campos específicos:

# Comprueba solo el estado de energía
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,running,status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Respuesta:

{
  "powerstate": true,
  "running": true,
  "status": "running"
}

Supervisión de cambios en el estado de energía

import time
import requests

def wait_for_power_state(machine_id, desired_state, max_retries=10):
    """Esperar a que la VM alcance el estado de energía deseado"""
    for attempt in range(max_retries):
        response = requests.get(
            f"https://your-vergeos.example.com/api/v4/machine_status/{machine_id}",
            params={"fields": "powerstate,running,status"},
            headers={"Authorization": "Bearer YOUR_API_KEY"}
        )
        
        data = response.json()
        if data.get("powerstate") == desired_state:
            return True
            
        time.sleep(5)  # Espera 5 segundos entre comprobaciones
    
    return False

# Ejemplo de uso
if wait_for_power_state("54", True):
    print("La VM ahora se está ejecutando")
else:
    print("La VM no pudo iniciarse dentro del tiempo de espera")

Flujos de trabajo comunes de administración de energía

Flujo de trabajo de apagado seguro de la VM

# Paso 1: Intentar un apagado gradual
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"action": "poweroff", "vm": "42"}'

# Paso 2: Esperar y comprobar el estado (repetir según sea necesario)
sleep 30
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,status" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Paso 3: Forzar el apagado si el gradual falló (después de un tiempo de espera razonable)
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"action": "kill", "vm": "42"}'

Flujo de trabajo de reinicio de la VM

# Paso 1: Reinicio gradual
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "action": "reset",
    "params": {"graceful": true},
    "vm": "42"
  }'

# Paso 2: Supervisar el progreso del reinicio
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=powerstate,status,node" \
  -H "Authorization: Bearer YOUR_API_KEY"

Gestión de errores

Errores comunes de administración de energía

Error: 409 Conflicto - La VM ya está en ejecución

{
  "error": "No se puede encender la VM: ya está en estado en ejecución"
}

Solución: Compruebe el estado de energía actual antes de enviar comandos de encendido.

Error: 409 Conflicto - VM no en ejecución

{
  "error": "No se puede apagar la VM: no está en estado de ejecución"
}

Solución: Verifica que la VM realmente se esté ejecutando antes de intentar apagarla.

Error: 507 Recursos insuficientes

{
  "error": "Recursos insuficientes del clúster para iniciar la VM"
}

Solución: Comprueba la disponibilidad de recursos del clúster o reduce los requisitos de recursos de la VM.

Tiempos de espera de la operación

Establece tiempos de espera adecuados para las operaciones de energía:

• Encendido: 30-60 segundos
• Apagado gradual: 60-120 segundos
• Apagado forzado: 10-30 segundos
• Reinicie: 60-120 segundos

Operaciones relacionadas

• Creación de VM: consulta Creación de VM para crear VMs
• Configuración: consulta Configuración de la VM para cambios de CPU/RAM
• Operaciones avanzadas: consulta Operaciones avanzadas de VM para clonación y instantáneas

¿Necesitas ayuda?

Para obtener soporte adicional con la gestión de energía de la VM:

• Consulta el portal de documentación de VergeOS
• Contacta con el soporte de VergeOS con mensajes de error específicos
• Revisa los registros del sistema para obtener información detallada del error
• Consulta los foros de la comunidad de VergeOS