API de creación de VM

Guía completa para crear máquinas virtuales en VergeOS, incluida la creación básica, configuraciones basadas en recetas, discos, dispositivos e interfaces de red

Puntos clave

• Crea VMs con parámetros esenciales de configuración usando la API REST

• Compatibilidad con la creación de VMs basada en recetas con configuraciones complejas

• Agrega unidades, dispositivos e interfaces de red después de crear la VM

• Comprende las diferencias entre clave de VM y clave de máquina para distintas operaciones

Esta guía cubre la creación de máquinas virtuales en VergeOS, desde la creación básica de VM hasta la adición de unidades, dispositivos e interfaces de red. La API de VergeOS proporciona endpoints completos para la creación de VM y la configuración de hardware.

Etapa: Creación de VM (1 de 4) Entrada: credenciales de API, información del clúster, especificaciones de la VM Salida: clave de VM (42) + clave de máquina (54) Siguiente: usa las claves para la gestión de energía Siguientes pasos comunes:

• Encender VM → Gestión de energía de la VM

• Configurar ajustes → Configuración de la VM

• Operaciones avanzadas → Operaciones avanzadas de VM

Este documento ayuda con

• "Cómo crear una VM mediante la API"

• "Cómo agregar unidades durante la configuración de la VM"

• "Cómo adjuntar dispositivos GPU/PCI a las VMs"

• "Creación de VM con cloud-init"

• "Comprender las claves de VM frente a las de máquina"

• "Cómo configurar interfaces de red para nuevas VMs"

• "Provisionamiento de VM basado en recetas"

• "Automatización de creación masiva de VMs"

• "Despliegue de VMs como código de infraestructura"

Referencia rápida

Puntos finales principales

• Crear VM: POST /api/v4/vms

• Agregar unidad: POST /api/v4/machine_drives

• Agregar dispositivo: POST /api/v4/machine_devices

• Agregar NIC: POST /api/v4/machine_nics

Parámetros clave

• name: identificador de la VM (obligatorio)

• cluster: ID del clúster de destino

• machine: ID de la máquina de la creación de la VM (para añadir hardware)

• resource_group: UUID para passthrough de dispositivos

Autenticación

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

Siguientes pasos

Después de crear la VM → Gestión de energía (Gestión de energía de la VM)

Referencia rápida de la API

Operación	Método	Punto final	Tipo de clave	Propósito
Crear VM	POST	/api/v4/vms	Devuelve ambas	Creación inicial
Agregar unidad	POST	/api/v4/machine_drives	Clave de máquina	Hardware
Agregar dispositivo	POST	/api/v4/machine_devices	Clave de máquina	passthrough de GPU/PCI
Agregar NIC	POST	/api/v4/machine_nics	Clave de máquina	Interfaz de red
Encendido	POST	/api/v4/vm_actions	clave de VM	Control
Comprobar estado	GET	/api/v4/machine_status/{id}	Clave de máquina	Monitorear

Índice de resolución de problemas

• 409 Conflicto: el nombre de la VM ya existe, ya está en ejecución, permiso denegado

• 400 Solicitud incorrecta: parámetros inválidos, faltan campos obligatorios, JSON inválido

• 507 Almacenamiento insuficiente: nivel lleno, reduce el tamaño, elige un nivel diferente

• 403 Prohibido: permisos de la clave API, acceso al clúster denegado

• 404 No encontrado: ID de clúster inválido, falta la fuente de medios, grupo de recursos inválido

• 422 Entidad no procesable: interfaz de unidad inválida, tipo de medio no compatible

Requisitos previos

• Credenciales válidas de la API de VergeOS con permisos de gestión de VM

• Comprensión de los conceptos de VergeOS: clústeres, vnets, fuentes de medios y grupos de recursos

• Conocimientos básicos de los principios de API REST y del formato JSON

Autenticación

Todas las operaciones de creación de VM requieren autenticación usando una de las siguientes opciones:

• Clave API: inclúyela en el Authorization encabezado como Bearer YOUR_API_KEY

• Autenticación básica: nombre de usuario y contraseña para sesiones interactivas

• Token de sesión: para integraciones basadas en web

# Uso de clave API
curl -H "Authorization: Bearer YOUR_API_KEY" \\
     -H "Content-Type: application/json" \\
     https://your-vergeos.example.com/api/v4/vms

Creación básica de VM

POST /api/v4/vms

Descripción: crea una nueva máquina virtual con la configuración especificada.

Parámetros de la solicitud:

Nombre	Tipo	Obligatorio	Descripción
name	cadena	Sí	Nombre único de la VM
description	cadena	No	Descripción de la VM
cluster	cadena	No	ID del clúster de destino (cadena numérica)
ram	entero	No	RAM en MB (predeterminado: 1024)
cpu_cores	entero	No	Número de núcleos de CPU (predeterminado: 1)
guest_agent	cadena	No	Habilitar el agente invitado ("true"/"false")
console_pass_hash	cadena	No	Hash de la contraseña de la consola (cadena vacía si no se usa)
video	cadena	No	Tipo de adaptador de video (virtio, std, cirrus, etc.)
rtc_base	cadena	No	Configuración base del RTC (utc, localtime)
uefi	cadena	No	Habilitar arranque UEFI ("true"/"false")

Ejemplo del cuerpo de la solicitud:

{
  "name": "web-server-01",
  "description": "Servidor web de producción",
  "cluster": "1",
  "ram": 8192,
  "cpu_cores": 4,
  "guest_agent": "true",
  "console_pass_hash": "",
  "video": "virtio",
  "rtc_base": "utc",
  "uefi": "true"
}

Ejemplo de respuesta:

{
  "location": "/v4/vms/42",
  "dbpath": "vms/42",
  "$row": 42,
  "$key": "42",
  "response": {
    "machine": "54"
  }
}

Campos de respuesta:

Campo	Tipo	Descripción
location	cadena	Punto final de la API para la VM creada
dbpath	cadena	Ruta de base de datos para el registro de la VM
$row	entero	Número de fila de la base de datos
$key	cadena	ID de la VM (usado para llamadas posteriores a la API)
response.machine	cadena	ID de la máquina (usado para unidades, NIC y dispositivos)

Respuestas de error:

• 400 Solicitud incorrecta: parámetros de configuración inválidos

• 409 Conflicto: el nombre de la VM ya existe

• 403 Prohibido: permisos insuficientes

Clave de VM frente a clave de máquina

• clave de VM (p. ej., "42"): úsala para ajustes de la VM como CPU, RAM y consola

• Clave de máquina (p. ej., "54"): úsala para hardware como unidades, NIC y dispositivos

• Obtienes ambas claves en la respuesta de creación de la VM

Creación de VM basada en recetas

VergeOS admite la creación compleja de VMs usando recetas que incluyen unidades, interfaces de red y dispositivos.

VM completa con configuración de receta

{
  "name": "enterprise-vm",
  "description": "Servidor de aplicaciones empresarial",
  "cluster": "1",
  "cpu_cores": 8,
  "ram": 16384,
  "guest_agent": "true",
  "video": "virtio",
  "rtc_base": "utc",
  "uefi": "true",
  "secure_boot": "true",
  "console_pass_hash": "",
  "cloudinit_datasource": "nocloud",
  "cloudinit_files": [
    {
      "name": "user-data",
      "contents": "#cloud-config\nusers:\n  - name: admin\n    sudo: ALL=(ALL) NOPASSWD:ALL\n    ssh_authorized_keys:\n      - ssh-rsa AAAAB3NzaC1yc2E..."
    },
    {
      "name": "meta-data",
      "contents": "instance-id: enterprise-vm-001\nlocal-hostname: enterprise-vm"
    }
  ]
}

Agregar unidades

Las unidades deben crearse por separado después de crear la VM usando el endpoint de unidades de máquina.

POST /api/v4/machine_drives

Parámetros de la solicitud:

Nombre	Tipo	Obligatorio	Descripción
machine	cadena	Sí	ID de la máquina de la creación de la VM
name	cadena	No	Nombre de la unidad
medio	cadena	No	Tipo de medio (disco, cdrom, import, clone, efidisk)
interfaz	cadena	No	Interfaz de la unidad (virtio-scsi, ide, ahci, etc.)
disksize	entero	No	Tamaño del disco en bytes (para discos nuevos)
preferred_tier	cadena	No	Nivel de almacenamiento (1-5)
media_source	cadena	No	ID del medio de origen (para importación/clonación/cdrom)
show_pt	cadena	No	Anular nivel preferido ("true"/"false") - reemplaza el nivel predeterminado de la fuente de medios

Creación de una unidad de arranque

{
  "machine": "54",
  "name": "Unidad de SO",
  "media": "disk",
  "interface": "virtio-scsi",
  "disksize": 2199023255552,
  "preferred_tier": "1"
}

Ejemplo de respuesta:

{
  "location": "/v4/machine_drives/54",
  "dbpath": "machine_drives/54",
  "$row": 54,
  "$key": "54"
}

Adjuntar CDROM/ISO

{
  "machine": "54",
  "media": "cdrom",
  "interface": "ahci",
  "media_source": "7"
}

Ejemplo de respuesta:

{
  "location": "/v4/machine_drives/55",
  "dbpath": "machine_drives/55",
  "$row": 55,
  "$key": "55"
}

Importando desde la fuente de medios

{
  "machine": "54",
  "name": "Ubuntu Server",
  "description": "Ubuntu 22.04 LTS",
  "interface": "virtio-scsi",
  "media": "import",
  "media_source": 123,
  "preferred_tier": "3"
}

Agregar dispositivos (GPU, passthrough PCI, etc.)

POST /api/v4/machine_devices

Descripción: adjunta dispositivos de hardware como GPU, dispositivos PCI, dispositivos USB o TPM a una máquina virtual.

Parámetros de la solicitud:

Nombre	Tipo	Obligatorio	Descripción
machine	cadena	Sí	ID de máquina
resource_group	cadena	Sí	UUID del grupo de recursos para el dispositivo
settings_args	objeto	No	Configuración específica del dispositivo (objeto vacío para passthrough básico)

GPU con passthrough PCI

{
  "machine": "54",
  "resource_group": "1f67f07e-f653-db95-c475-01b8a2ea0ff1",
  "settings_args": {}
}

Ejemplo de respuesta:

{
  "location": "/v4/machine_devices/2",
  "dbpath": "machine_devices/2",
  "$row": 2,
  "$key": "2",
  "response": {
    "uuid": "934e250b-a13c-bd8f-104d-a31995b06eba"
  }
}

Encontrar grupos de recursos

El resource_group parámetro identifica el dispositivo de hardware específico que se va a adjuntar. Usa estos puntos finales para encontrar los UUID de grupos de recursos disponibles:

• GET /api/v4/resource_groups - Dispositivos de hardware generales (GPU, dispositivos PCI, USB, etc.)

• GET /api/v4/node_nvidia_vgpu_devices - Dispositivos NVIDIA vGPU específicamente

Encontrar dispositivos disponibles

# Dispositivos de hardware generales
curl "https://your-vergeos.example.com/api/v4/resource_groups" \\
  -H "Authorization: Bearer YOUR_API_KEY"

# Dispositivos NVIDIA vGPU
curl "https://your-vergeos.example.com/api/v4/node_nvidia_vgpu_devices" \\
  -H "Authorization: Bearer YOUR_API_KEY"

Agregar interfaces de red

POST /api/v4/machine_nics

Parámetros de la solicitud:

Nombre	Tipo	Obligatorio	Descripción
machine	cadena	Sí	ID de máquina
vnet	cadena	Sí	ID de red virtual (clave de la red de destino)
name	cadena	No	Nombre de la NIC
interfaz	cadena	No	Tipo de interfaz de NIC (virtio, e1000, etc.)
habilitado	booleano	No	Estado habilitado de la NIC

Ejemplo:

{
  "machine": "54",
  "vnet": "3"
}

Ejemplo de respuesta:

{
  "location": "/v4/machine_nics/78",
  "dbpath": "machine_nics/78",
  "$row": 78,
  "$key": "78"
}

Claves de red virtual

El vnet El parámetro usa la clave/ID de la red. Por ejemplo, vnet "3" podría ser tu red externa. Puedes encontrar las claves de red enumerando las redes disponibles mediante el punto final de la API de redes.

Ejemplo completo de creación de VM

Aquí tienes un flujo de trabajo completo para crear una VM con unidades, dispositivos e interfaces de red:

# Paso 1: Crear la VM
curl -X POST "https://your-vergeos.example.com/api/v4/vms" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "production-server",
    "description": "Servidor de aplicaciones de producción",
    "cluster": "1",
    "ram": 16384,
    "cpu_cores": 8,
    "guest_agent": "true",
    "video": "virtio",
    "uefi": "true"
  }'

# Respuesta: clave de VM = 42, clave de máquina = 54

# Paso 2: Agregar unidad de arranque
curl -X POST "https://your-vergeos.example.com/api/v4/machine_drives" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "name": "Unidad de arranque",
    "media": "disk",
    "interface": "virtio-scsi",
    "disksize": 107374182400,
    "preferred_tier": "1"
  }'

# Paso 3: Agregar interfaz de red
curl -X POST "https://your-vergeos.example.com/api/v4/machine_nics" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "vnet": "3"
  }'

# Paso 4: Agregar GPU (opcional)
curl -X POST "https://your-vergeos.example.com/api/v4/machine_devices" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "machine": "54",
    "resource_group": "1f67f07e-f653-db95-c475-01b8a2ea0ff1",
    "settings_args": {}
  }'

Operaciones relacionadas

• Gestión de energía: consulta Gestión de energía de la VM para iniciar/detener 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 creación 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