API de configuración de VM

Guía completa para modificar configuraciones de VM en VergeOS, incluyendo actualizaciones de CPU/RAM, notas, gestión de discos y gestión de interfaces de red

Puntos clave

• Modificar la configuración de la VM como CPU, RAM, consola y video mediante la API REST
• Administrar discos con capacidades de redimensionamiento, adición y eliminación
• Actualizar las interfaces de red y sus configuraciones
• Agregar notas de documentación a las VMs para el seguimiento operativo

Esta guía cubre la modificación de las configuraciones de máquinas virtuales en VergeOS después de su creación, incluidas las actualizaciones de CPU/RAM, la gestión de discos, los cambios de interfaces de red y la adición de notas operativas.

Etapa: Configuración de la VM (3 de 4) Entrada: clave de la VM (42) + clave de la máquina (54), cambios de configuración Salida: Configuración de VM actualizada, hardware modificado Anterior: VM encendida → Gestión de energía de la VM Siguientes pasos comunes:

• Operaciones avanzadas → Operaciones avanzadas de VM
• Ciclo de energía para los cambios → Gestión de energía de la VM

Este documento ayuda con

• "Cómo cambiar la CPU y la RAM de una VM"
• "Agregar unidades de almacenamiento a VMs existentes"
• "Redimensionar unidades y almacenamiento de la VM"
• "Administrar interfaces de red de la VM"
• "Agregar notas y documentación a las VMs"
• "Operaciones de hotplug y cambios en vivo"
• "Ajuste del rendimiento de la VM"
• "Flujos de trabajo de expansión de almacenamiento"
• "Reconfiguración de red"

Referencia rápida

Puntos finales principales

• Configuración de la VM: PUT /api/v4/vms/{id}
• Notas de la VM: POST /api/v4/note_actions
• Gestión de discos: POST/PUT/DELETE /api/v4/machine_drives
• Gestión de NIC: POST/PUT/DELETE /api/v4/machine_nics

Conceptos clave

• clave de VM: Úselo para la configuración de la VM (CPU, RAM, consola)
• Clave de máquina: Úselo para hardware (discos, NIC, dispositivos)
• Conexión en caliente: Algunos cambios requieren reiniciar la 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
Actualizar VM	PUT	/api/v4/vms/{id}	clave de VM	Configuración de CPU, RAM y consola
Agregar nota	POST	/api/v4/note_actions	clave de VM	Documentación
Agregar unidad	POST	/api/v4/machine_drives	Clave de máquina	Expansión de almacenamiento
Redimensionar disco	PUT	/api/v4/machine_drives/{id}	Clave del disco	Aumentar el tamaño del disco
Eliminar disco	DELETE	/api/v4/machine_drives/{id}	Clave del disco	Eliminación de almacenamiento
Agregar NIC	POST	/api/v4/machine_nics	Clave de máquina	Interfaz de red
Actualizar NIC	PUT	/api/v4/machine_nics/{id}	Clave de la NIC	Cambios de red
Eliminar NIC	DELETE	/api/v4/machine_nics/{id}	Clave de la NIC	Eliminación de la interfaz

Índice de resolución de problemas

• 400 Solicitud incorrecta: Tamaño de RAM inválido, cantidad de CPU inválida, JSON malformado
• 409 Conflicto: La VM debe estar detenida, hotplug no admitido, recurso en uso
• 507 Almacenamiento insuficiente: Nivel lleno, tamaño de disco demasiado grande, cuota excedida
• 403 Prohibido: Permisos de clave API, acceso a VM denegado, restricciones del clúster
• 422 Entidad no procesable: El disco no puede reducirse, tipo de interfaz inválido
• 404 No encontrado: VM no encontrada, disco no encontrado, NIC no encontrada, vnet inválida

Actualizaciones de CPU y RAM

PUT /api/v4/vms/{id}

Descripción: Actualiza la configuración de la VM. Usa la clave de la VM (no la clave de la máquina) para la configuración a nivel de VM.

Ejemplo del cuerpo de la solicitud:

{
  "ram": 16384,
  "cpu_cores": 3,
  "console": "spice",
  "video": "qxl",
  "show_advanced": "true",
  "nested_virtualization": "true",
  "disable_hypervisor": "true"
}

Llamada API completa:

curl -X PUT "https://your-vergeos.example.com/api/v4/vms/42" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "ram": 16384,
    "cpu_cores": 3,
    "console": "spice",
    "video": "qxl",
    "show_advanced": "true",
    "nested_virtualization": "true",
    "disable_hypervisor": "true"
  }'

Parámetros comunes de configuración

Parámetro	Tipo	Descripción	Se requiere reinicio
ram	entero	RAM en MB	Normalmente sí
cpu_cores	entero	Cantidad de núcleos de CPU	Normalmente sí
consola	cadena	Tipo de consola (spice, vnc, none)	En el próximo inicio
video	cadena	Adaptador de video (qxl, virtio, std, cirrus)	En el próximo inicio
nested_virtualization	cadena	Habilitar virtualización anidada ("true"/"false")	Sí
disable_hypervisor	cadena	Deshabilitar hipervisor ("true"/"false")	Sí
guest_agent	cadena	Habilitar el agente invitado ("true"/"false")	En el próximo inicio
uefi	cadena	Habilitar arranque UEFI ("true"/"false")	Sí
secure_boot	cadena	Habilitar arranque seguro ("true"/"false")	Sí

Clave de VM frente a clave de máquina

• Configuración de la VM (CPU, RAM, consola, video): Use la clave de la VM (por ejemplo, 42) con /api/v4/vms/{vm_key}
• Cambios de hardware (discos, NIC, dispositivos): Use la clave de la máquina (por ejemplo, 54) con /api/v4/machine_* puntos finales

Cambios de configuración

• Los cambios de CPU y RAM suelen requerir reiniciar la VM
• Los cambios de consola y video surten efecto en el siguiente inicio de la VM
• La virtualización anidada y la configuración del hipervisor requieren reiniciar la VM
• Siempre revise allow_hotplug configuración para capacidades de hot-add

Agregar notas a las VMs

POST /api/v4/note_actions

Descripción: Agrega o actualiza notas para una VM en la interfaz de VergeOS con fines de documentación.

Cuerpo de la solicitud:

{
  "owner": "vms/42",
  "action": "update",
  "params": {
    "text": "Esta VM es de prueba"
  }
}

Llamada API completa:

curl -X POST "https://your-vergeos.example.com/api/v4/note_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "owner": "vms/42",
    "action": "update",
    "params": {
      "text": "Servidor web de producción - Actualizado 2025-08-24"
    }
  }'

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
propietario	cadena	Sí	Identificador del recurso (formato: "vms/{vm_key}")
action	cadena	Sí	Acción a realizar ("update")
params.text	cadena	Sí	Contenido del texto de la nota

Notas de la VM

Las notas son visibles en la interfaz de VergeOS y ayudan con la documentación de la VM, los calendarios de mantenimiento o los detalles de configuración. Use la clave de la VM (no la clave de la máquina) en el campo owner.

Gestión de discos

Agregar nuevos discos

Use el endpoint de machine drives para agregar almacenamiento después de crear la VM:

POST /api/v4/machine_drives

{
  "machine": "54",
  "name": "Unidad de datos",
  "interface": "virtio-scsi",
  "media": "disk",
  "disksize": 536870912000,
  "preferred_tier": "2"
}

Llamada API completa:

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 datos",
    "interface": "virtio-scsi",
    "media": "disk",
    "disksize": 536870912000,
    "preferred_tier": "2"
  }'

Redimensionar discos

PUT /api/v4/machine_drives/{drive_id}

Descripción: Aumenta el tamaño de un disco existente. Tenga en cuenta que los discos solo pueden expandirse, no reducirse.

{
  "disksize": 1073741824000
}

Llamada API completa:

curl -X PUT "https://your-vergeos.example.com/api/v4/machine_drives/55" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "disksize": 1073741824000
  }'

Redimensionamiento de disco

• Los discos solo pueden expandirse, nunca reducirse
• Es posible que sea necesario configurar el sistema operativo invitado para que reconozca el nuevo tamaño
• Algunos sistemas de archivos requieren expansión manual después de redimensionar el disco

Eliminación de discos

Antes de eliminarlos, los discos deben desconectarse en caliente si la VM está en ejecución:

Paso 1: Desconectar el disco en caliente (si la VM está en ejecución)

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": "hotplugdrive",
    "params": {
      "device": "drive-id-here",
      "unplug": true
    }
  }'

Paso 2: Eliminar el disco

DELETE /api/v4/machine_drives/{drive_id}

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

Ejemplos de gestión de discos

Agregar un CDROM/ISO

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

Agregar una unidad de importación

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

Gestión de interfaces de red

Agregar NICs

POST /api/v4/machine_nics

{
  "machine": "54",
  "name": "Red secundaria",
  "interface": "virtio",
  "vnet": "8",
  "enabled": true
}

Llamada API completa:

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",
    "name": "Red secundaria",
    "interface": "virtio",
    "vnet": "8",
    "enabled": true
  }'

Actualización de la configuración de NIC

PUT /api/v4/machine_nics/{nic_id}

{
  "vnet": "10",
  "enabled": true
}

Llamada API completa:

curl -X PUT "https://your-vergeos.example.com/api/v4/machine_nics/78" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "vnet": "10",
    "enabled": true
  }'

Eliminar NICs

DELETE /api/v4/machine_nics/{nic_id}

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

Parámetros de configuración de NIC

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

Claves de red virtual

El vnet El parámetro usa la clave/ID de la red. Puede encontrar las claves de red enumerando las redes disponibles mediante el endpoint de la API de redes.

Flujo de trabajo completo de configuración

Aquí hay un ejemplo de actualización de la configuración completa de una VM:

# Paso 1: Actualizar la configuración de la VM (CPU, RAM, consola)
curl -X PUT "https://your-vergeos.example.com/api/v4/vms/42" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "ram": 32768,
    "cpu_cores": 8,
    "console": "spice",
    "video": "virtio"
  }'

# Paso 2: Agregar nota operativa
curl -X POST "https://your-vergeos.example.com/api/v4/note_actions" \
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "owner": "vms/42",
    "action": "update",
    "params": {
      "text": "Actualizada a 32 GB de RAM y 8 núcleos para aumentar la carga de trabajo - 2025-08-24"
    }
  }'

# Paso 3: Agregar almacenamiento adicional
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": "Datos de la aplicación",
    "interface": "virtio-scsi",
    "media": "disk",
    "disksize": 1073741824000,
    "preferred_tier": "2"
  }'

# Paso 4: Agregar interfaz de red secundaria
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",
    "name": "Red de gestión",
    "interface": "virtio",
    "vnet": "5",
    "enabled": true
  }'

Mejores prácticas de configuración

Antes de realizar cambios

1. Verificar el estado de la VM: Asegúrese de que la VM esté en un estado apropiado para los cambios
2. Respaldar los datos importantes: Cree instantáneas antes de cambios importantes
3. Revisar dependencias: Considere el impacto en las aplicaciones en ejecución
4. Planificar tiempo de inactividad: Algunos cambios requieren reiniciar la VM

Después de realizar cambios

1. Verificar la configuración: Verifique que los cambios se hayan aplicado correctamente
2. Probar funcionalidad: Asegúrese de que la VM funcione como se espera
3. Actualizar documentación: Agregue notas sobre los cambios de configuración
4. Supervisar rendimiento: Observe cualquier impacto en el rendimiento

Consideraciones sobre hotplug

# Verificar si la VM admite hotplug
curl "https://your-vergeos.example.com/api/v4/vms/42?fields=allow_hotplug" \
  -H "Authorization: Bearer YOUR_API_KEY"

Compatibilidad con hotplug

El allow_hotplug la configuración habilita la adición y eliminación en caliente de discos y NIC mientras la VM está en ejecución:

• Unidades: Se puede agregar/eliminar sobre la marcha (el SO invitado debe admitirlo; se recomienda Virtio-SCSI)
• NIC: Se puede agregar/eliminar sobre la marcha (ampliamente compatible con sistemas operativos invitados)
• CPU/RAM: Los cambios siempre requieren un ciclo de energía de la VM

Consulte Capacidades de hot-plug de la VM para obtener todos los detalles.

Gestión de errores

Errores comunes de configuración

Error: 400 Solicitud incorrecta - Tamaño de RAM inválido

{
  "error": "El tamaño de la RAM debe ser al menos 512 MB y como máximo 1048576 MB"
}

Error: 409 Conflicto - La VM debe estar detenida

{
  "error": "No se pueden modificar los núcleos de CPU mientras la VM está en ejecución sin compatibilidad con hotplug"
}

Solución: Detenga la VM o verifique las capacidades de hotplug antes de realizar cambios.

Error: 507 Almacenamiento insuficiente

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

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

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
• Operaciones avanzadas: consulta Operaciones avanzadas de VM para clonación y instantáneas

¿Necesitas ayuda?

Para obtener soporte adicional con la configuración 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