API de operaciones avanzadas de VM

Guía completa de operaciones avanzadas de VM en VergeOS, incluidas clonación, instantáneas, eliminación y solución de problemas

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

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

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

Requisitos previos

La VM debe existir → Ver Creación de VM

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

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

Ejemplo de respuesta:

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

Opciones avanzadas de clonación

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

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

Ejemplo de flujo de trabajo de clonación

# 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

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

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 '{
    "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

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

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 '{
    "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:

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:

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

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

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.

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

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)

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

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)

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

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

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.

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

# 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

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

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

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

{
  "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:

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

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

# 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

# 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

# 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

Operaciones relacionadas

• Creación de VM: consulta Creación de VM para la configuración inicial de la VM

• Gestión de energía: consulta Gestión de energía de la VM para operaciones de inicio/detención

• Configuración: consulta Configuración de la VM para cambios de CPU/RAM

¿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