> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/knowledge-base/es/automation-api/vm-power-management.md).

# API de gestión de energía de VM

{% hint style="info" %}
**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
  {% endhint %}

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`](/knowledge-base/es/automation-api/vm-creation-api.md) **Siguientes pasos comunes**:

* Configurar ajustes de la VM → [`Configuración de la VM`](/knowledge-base/es/automation-api/vm-configuration.md)
* Operaciones avanzadas → [`Operaciones avanzadas de VM`](/knowledge-base/es/automation-api/vm-advanced-operations.md)

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

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

### Requisitos previos

La VM debe crearse primero → Ver [`Creación de VM`](/knowledge-base/es/automation-api/vm-creation-api.md)

## 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**:

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

**Llamada API completa**:

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

{% hint style="success" %}
**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
  {% endhint %}

## Deteniendo VMs

### Apagado gradual (ACPI)

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

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

**Llamada API completa**:

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

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

**Llamada API completa**:

```bash
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"
  }'
```

{% hint style="warning" %}
**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.
{% endhint %}

## Reiniciando VMs

### Reinicio gradual (ACPI)

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

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

**Llamada API completa**:

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

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

**Llamada API completa**:

```bash
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**:

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

**Ejemplo de respuesta**:

```json
{
  "$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**:

```bash
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

```json
{
  "$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

```json
{
  "$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": []
}
```

{% hint style="success" %}
**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
  {% endhint %}

{% hint style="success" %}
**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)
  {% endhint %}

## 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:

```bash
# 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**:

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

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

```python
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

```bash
# 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

```bash
# 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`

```json
{
  "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`

```json
{
  "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`

```json
{
  "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

{% hint style="info" %}
**Operaciones relacionadas**

* **Creación de VM**: consulta [`Creación de VM`](/knowledge-base/es/automation-api/vm-creation-api.md) para crear VMs
* **Configuración**: consulta [`Configuración de la VM`](/knowledge-base/es/automation-api/vm-configuration.md) para cambios de CPU/RAM
* **Operaciones avanzadas**: consulta [`Operaciones avanzadas de VM`](/knowledge-base/es/automation-api/vm-advanced-operations.md) para clonación y instantáneas
  {% endhint %}

{% hint style="info" %}
**¿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
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/knowledge-base/es/automation-api/vm-power-management.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.