> 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-advanced-operations.md).

# API de operaciones avanzadas de VM

{% hint style="info" %}
**Puntos clave**

* Clonar VMs con configuración completa y copia de discos
* Crear y restaurar instantáneas de VM para respaldo y recuperación
* Eliminar VMs de forma segura con limpieza automática de recursos
* Gestión integral de errores y orientación para la solución de problemas
  {% endhint %}

Esta guía cubre operaciones avanzadas de máquinas virtuales en VergeOS, incluyendo clonación, gestión de instantáneas, eliminación y solución de problemas. Estas operaciones proporcionan capacidades potentes para la gestión del ciclo de vida de las VM y la recuperación ante desastres.

**Etapa**: Operaciones avanzadas de VM (4 de 4) **Entrada**: clave de VM (42), tipo de operación, parámetros **Salida**: VMs clonadas, instantáneas, confirmación de limpieza **Anterior**: VM configurada → [`Configuración de la VM`](/knowledge-base/es/automation-api/vm-configuration.md) **Operaciones comunes**:

* Clonar para plantillas → Nuevo ciclo de creación de VM
* Instantánea para respaldo → Flujos de recuperación
* Eliminar para limpieza → Fin del ciclo de vida

## Este documento ayuda con

* "Cómo clonar VMs mediante API"
* "Creación de instantáneas y copias de seguridad de VM"
* "Restauración de VMs desde instantáneas"
* "Eliminación segura de VMs y limpieza"
* "Solución de problemas y diagnóstico de VM"
* "Flujos de trabajo de creación de plantillas"
* "Operaciones de recuperación ante desastres"
* "Gestión masiva de VMs"
* "Automatización de la limpieza de recursos"

## Referencia rápida

### Puntos finales principales

* **Acciones de VM**: `POST /api/v4/vm_actions`
* **Eliminación de VM**: `DELETE /api/v4/vms/{vm_key}`
* **Listado de VMs**: `GET /api/v4/vms`

### Acciones clave

* `clonar`: Crear copia completa de la VM
* `instantánea`: Crear instantánea de la VM
* `restaurar`: Restaurar desde la instantánea

### Autenticación

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

### Requisitos previos

La VM debe existir → 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                             |
| ---------------------- | ------ | ----------------------------- | ------------------ | ------------------------------------- |
| Clonar VM              | POST   | `/api/v4/vm_actions`          | clave de VM        | Crear copia completa                  |
| Crear instantánea      | POST   | `/api/v4/vm_actions`          | clave de VM        | Copia de seguridad en un momento dado |
| Restaurar instantánea  | POST   | `/api/v4/vm_actions`          | clave de VM        | Operación de recuperación             |
| Listar instantáneas    | GET    | `/api/v4/vms`                 | Consulta de filtro | Encontrar instantáneas                |
| Eliminar VM            | DELETE | `/api/v4/vms/{id}`            | clave de VM        | Eliminación completa                  |
| Estado de la VM        | GET    | `/api/v4/vms/{id}`            | clave de VM        | Verificación de configuración         |
| Estado de la operación | GET    | `/api/v4/machine_status/{id}` | Clave de máquina   | Monitorización en tiempo de ejecución |

## Índice de resolución de problemas

* **409 Conflicto**: El nombre de clon ya existe, la VM ya está en ejecución, operación en curso
* **507 Almacenamiento insuficiente**: No hay suficiente espacio para el clon, el almacenamiento de instantáneas está lleno
* **403 Prohibido**: Permisos de clave API, acceso a VM denegado, restricciones del clúster
* **404 No encontrado**: VM no encontrada, instantánea no encontrada, clave de VM no válida
* **408 Tiempo de espera de la solicitud**: Tiempo de espera de la operación de clonación, tiempo de espera de la creación de instantánea
* **422 Entidad no procesable**: Parámetros de clonación no válidos, conflicto en la restauración de la instantánea
* **500 Error interno del servidor**: Problemas del sistema de almacenamiento, problemas del hipervisor, fallos del clúster

## Clonación de VM

### POST /api/v4/vm\_actions

**Descripción**: Crea una copia completa de una VM, incluidos todos los discos y la configuración.

### Clonación básica

```json
{
  "params": {
    "name": "clon de prueba",
    "quiesce": "true"
  },
  "action": "clone",
  "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 '{
    "params": {
      "name": "clon de prueba",
      "quiesce": "true"
    },
    "action": "clone",
    "vm": "42"
  }'
```

**Ejemplo de respuesta**:

```json
{
  "response": {
    "vmkey": "43",
    "machinekey": "55",
    "machinestatuskey": "55",
    "clusterkey": "1"
  }
}
```

### Opciones avanzadas de clonación

```json
{
  "params": {
    "name": "clon-producción",
    "description": "Clon del servidor de producción para pruebas",
    "preserve_macs": "true",
    "preserve_device_uuids": "true",
    "quiesce": "true",
    "cluster": "2"
  },
  "action": "clone",
  "vm": "42"
}
```

### Parámetros de clonación

| Parámetro               | Tipo   | Obligatorio | Descripción                                                                     |
| ----------------------- | ------ | ----------- | ------------------------------------------------------------------------------- |
| name                    | cadena | Sí          | Nombre de la VM clonada                                                         |
| description             | cadena | No          | Descripción del clon                                                            |
| quiesce                 | cadena | No          | Pausar la VM antes de clonar ("true"/"false") para la consistencia de los datos |
| preserve\_macs          | cadena | No          | Conservar direcciones MAC ("true"/"false")                                      |
| preserve\_device\_uuids | cadena | No          | Conservar UUID de los dispositivos ("true"/"false")                             |
| cluster                 | cadena | No          | ID del clúster de destino                                                       |

{% hint style="success" %}
**Opciones de clonación**

* **Pausar**: Usar `"quiesce": "true"` para garantizar la consistencia de los datos pausando brevemente la VM
* **Conservar MACs**: Usar `"preserve_macs": "true"` para mantener las mismas direcciones MAC (puede causar conflictos de red)
* **Conservar UUID de dispositivos**: Usar `"preserve_device_uuids": "true"` para mantener los identificadores de los dispositivos
* **Entre clústeres**: Especifique un ID de clúster diferente para clonar a otro clúster
  {% endhint %}

### Ejemplo de flujo de trabajo de clonación

```bash
# Paso 1: Crear clon
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "params": {
      "name": "copia-de-seguridad-clon-$(date +%Y%m%d)",
      "description": "Clon de copia de seguridad automatizada",
      "quiesce": "true"
    },
    "action": "clone",
    "vm": "42"
  }'

# Paso 2: Verificar la creación del clon (usando el vmkey devuelto)
curl "https://your-vergeos.example.com/api/v4/vms/43?fields=name,description,created" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# Paso 3: Comprobar el estado de energía del clon
curl "https://your-vergeos.example.com/api/v4/machine_status/55?fields=powerstate,status" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Instantáneas de VM

### Creación de instantáneas

```json
{
  "vm": "42",
  "action": "snapshot",
  "params": {
    "name": "instantánea-previa-a-actualización",
    "description": "Antes de la actualización del sistema"
  }
}
```

**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 '{
    "vm": "42",
    "action": "snapshot",
    "params": {
      "name": "instantánea-previa-a-actualización",
      "description": "Antes de la actualización del sistema - $(date)"
    }
  }'
```

### Restauración desde instantáneas

```json
{
  "vm": "42",
  "action": "restore",
  "params": {
    "snapshot_id": "snapshot-67890"
  }
}
```

**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 '{
    "vm": "42",
    "action": "restore",
    "params": {
      "snapshot_id": "snapshot-67890"
    }
  }'
```

### Listado de instantáneas de VM

#### GET /api/v4/vms

Use filtros para encontrar instantáneas:

```bash
curl "https://your-vergeos.example.com/api/v4/vms?filter=is_snapshot%20eq%20true%20and%20name%20contains%20'web-server'" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Encontrar todas las instantáneas de una VM**:

```bash
curl "https://your-vergeos.example.com/api/v4/vms?filter=is_snapshot%20eq%20true%20and%20parent_vm%20eq%2042" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Flujo de trabajo de gestión de instantáneas

```bash
# Paso 1: Crear instantánea antes del mantenimiento
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "vm": "42",
    "action": "snapshot",
    "params": {
      "name": "instantánea-mantenimiento-$(date +%Y%m%d-%H%M)",
      "description": "Instantánea previa al mantenimiento"
    }
  }'

# Paso 2: Listar instantáneas para encontrar el ID de la instantánea
curl "https://your-vergeos.example.com/api/v4/vms?filter=is_snapshot%20eq%20true%20and%20parent_vm%20eq%2042&fields=name,description,created" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# Paso 3: Restaurar si es necesario (después de problemas de mantenimiento)
curl -X POST "https://your-vergeos.example.com/api/v4/vm_actions" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "vm": "42",
    "action": "restore",
    "params": {
      "snapshot_id": "found-snapshot-id"
    }
  }'
```

## Eliminación y limpieza de VM

### Eliminación completa de VM

#### DELETE /api/v4/vms/{vm\_key}

**Descripción**: Elimina una VM y quita automáticamente todos los recursos asociados, incluidos discos, NIC, dispositivos y configuraciones.

```bash
curl -X DELETE "https://your-vergeos.example.com/api/v4/vms/42" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

**Respuesta**: `200 OK` tras una eliminación exitosa.

{% hint style="success" %}
**Limpieza automática**

Cuando eliminas una VM usando `DELETE /api/v4/vms/{vm_key}`, VergeOS elimina automáticamente:

* **Todos los discos** adjuntos a la VM
* **Todas las interfaces de red** (NIC)
* **Todos los dispositivos** (GPU, paso directo PCI, USB, TPM, etc.)
* **Configuración de la VM** y metadatos
* **Archivos cloud-init** y configuraciones
* **Notas de la VM** y documentación
* **Recursos de máquina asociados**
  {% endhint %}

### Consideraciones previas a la eliminación

Antes de eliminar una VM, considere:

1. **Copia de seguridad de datos**: Asegúrese de que los datos importantes tengan copia de seguridad
2. **Instantáneas**: Las instantáneas de la VM pueden eliminarse con la VM
3. **Dependencias**: Compruebe si otros sistemas dependen de esta VM
4. **Configuración de red**: Anote cualquier configuración de red especial
5. **Licenciamiento**: Considere las implicaciones de la licencia del software

### Proceso de eliminación segura

#### Paso 1: Apagar la VM (recomendado)

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

#### Paso 2: Verificar el estado de energía

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

#### Paso 3: Crear copia de seguridad final (opcional)

```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 '{
    "params": {
      "name": "copia-final-antes-de-la-eliminación",
      "description": "Copia de seguridad final antes de la eliminación de la VM"
    },
    "action": "clone",
    "vm": "42"
  }'
```

#### Paso 4: Eliminar la VM y todos los recursos

```bash
curl -X DELETE "https://your-vergeos.example.com/api/v4/vms/42" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

{% hint style="success" %}
**Uso de la clave de VM**

Use la clave de VM (p. ej., `42`) de la respuesta de creación de la VM o del listado de VMs, no la clave de máquina. El proceso de eliminación gestiona automáticamente todos los recursos de máquina asociados.
{% endhint %}

### No se requiere limpieza manual

A diferencia de algunas plataformas de virtualización, VergeOS gestiona automáticamente la limpieza completa de recursos. No **no** necesita hacerlo manualmente:

* Eliminar discos individuales
* Quitar interfaces de red
* Desconectar dispositivos
* Limpiar archivos de configuración
* Eliminar entradas de estado de la máquina

La única `DELETE /api/v4/vms/{vm_key}` operación gestiona toda la limpieza automáticamente.

### Búsqueda de recursos huérfanos

```bash
# Encontrar discos sin máquinas asociadas
curl "https://your-vergeos.example.com/api/v4/machine_drives?filter=machine%20eq%20null" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# Encontrar NIC sin máquinas asociadas
curl "https://your-vergeos.example.com/api/v4/machine_nics?filter=machine%20eq%20null" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Gestión de errores y solución de problemas

### Escenarios de error comunes

#### Fallos en la creación de VM

**Error**: `400 Solicitud incorrecta - Tipo de máquina no válido`

```json
{
  "error": "machine_type 'invalid-type' no válido. Opciones válidas: pc, q35, pc-i440fx-*, pc-q35-*"
}
```

**Solución**: Use tipos de máquina válidos de la lista compatible.

#### Conflictos de estado 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.

#### Restricciones de recursos

**Error**: `507 Almacenamiento insuficiente`

```json
{
  "error": "Espacio de almacenamiento insuficiente en el nivel 3 para el tamaño de disco solicitado"
}
```

**Solución**: Elija otro nivel de almacenamiento o reduzca el tamaño del disco.

#### Fallos de clonación

**Error**: `409 Conflicto - El nombre del clon ya existe`

```json
{
  "error": "Ya existe una VM con el nombre 'clon de prueba'"
}
```

**Solución**: Use nombres únicos para las VMs clonadas.

### Monitorización de operaciones de VM

#### Comprobación del estado de la operación

Muchas operaciones de VM son asíncronas. Supervise el progreso usando:

```bash
# Comprobar estado de la VM
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=machine%23status" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# Comprobar el estado de la máquina para información en tiempo de ejecución
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=status,powerstate" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Tiempos de espera de la operación

Establezca tiempos de espera apropiados para operaciones de larga duración:

* **Creación de VM**: 5-10 minutos
* **Operaciones de clonación**: 10-30 minutos (según el tamaño)
* **Creación de instantáneas**: 2-5 minutos
* **Restauración de instantáneas**: 5-15 minutos
* **Cambios de estado de energía**: 30-60 segundos
* **Eliminación de VM**: 2-5 minutos

### Lógica de reintento

Implemente lógica de reintento para fallos transitorios:

```python
import time
import requests

def wait_for_operation_completion(vm_id, max_retries=20):
    """Esperar a que se complete la operación de la VM"""
    for attempt in range(max_retries):
        response = requests.get(
            f"https://your-vergeos.example.com/api/v4/vms/{vm_id}",
            params={"fields": "machine#status#status as operation_status"},
            headers={"Authorization": "Bearer YOUR_API_KEY"}
        )
        
        status = response.json().get("operation_status", "")
        if status not in ["cloning", "snapshotting", "restoring"]:
            return True
            
        time.sleep(10)  # Esperar 10 segundos entre comprobaciones
    
    return False

# Ejemplo de uso
if wait_for_operation_completion("42"):
    print("La operación se completó correctamente")
else:
    print("La operación agotó el tiempo de espera")
```

### Depuración de problemas de VM

#### Comprobar configuración de la VM

```bash
# Obtener la configuración completa de la VM
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=most" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Comprobar estado de la máquina

```bash
# Obtener estado en tiempo de ejecución y errores
curl "https://your-vergeos.example.com/api/v4/machine_status/54?fields=most" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Comprobar recursos del sistema

```bash
# Comprobar recursos del clúster
curl "https://your-vergeos.example.com/api/v4/clusters/1?fields=resources" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# Comprobar niveles de almacenamiento
curl "https://your-vergeos.example.com/api/v4/storage_tiers" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Mejores prácticas

1. **Pruebe siempre las operaciones** en entornos de desarrollo primero
2. **Cree instantáneas** antes de cambios importantes
3. **Supervise el uso de recursos** durante las operaciones
4. **Implemente una gestión adecuada de errores** en scripts de automatización
5. **Use nombres descriptivos** para clonaciones e instantáneas
6. **Limpie regularmente** los recursos no utilizados
7. **Documente los procedimientos operativos** para su equipo

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

* **Creación de VM**: consulta [`Creación de VM`](/knowledge-base/es/automation-api/vm-creation-api.md) para la configuración inicial de la VM
* **Gestión de energía**: consulta [`Gestión de energía de la VM`](/knowledge-base/es/automation-api/vm-power-management.md) para operaciones de inicio/detención
* **Configuración**: consulta [`Configuración de la VM`](/knowledge-base/es/automation-api/vm-configuration.md) para cambios de CPU/RAM
  {% endhint %}

{% hint style="info" %}
**¿Necesitas ayuda?**

Para obtener soporte adicional con las operaciones avanzadas de 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-advanced-operations.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.