> 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-configuration.md).

# API de configuración de VM

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

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

* Operaciones avanzadas → [`Operaciones avanzadas de VM`](/knowledge-base/es/automation-api/vm-advanced-operations.md)
* Ciclo de energía para los cambios → [`Gestión de energía de la VM`](/knowledge-base/es/automation-api/vm-power-management.md)

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

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

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

**Llamada API completa**:

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

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

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

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

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

**Llamada API completa**:

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

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

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

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

**Llamada API completa**:

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

```json
{
  "disksize": 1073741824000
}
```

**Llamada API completa**:

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

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

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

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

#### Paso 2: Eliminar el disco

#### DELETE /api/v4/machine\_drives/{drive\_id}

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

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

#### Agregar una unidad de importación

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

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

**Llamada API completa**:

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

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

**Llamada API completa**:

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

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

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

## Flujo de trabajo completo de configuración

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

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

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

{% hint style="success" %}
**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](/knowledge-base/es/tenants/vm-hotplug-capabilities.md) para obtener todos los detalles.
{% endhint %}

## Gestión de errores

### Errores comunes de configuración

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

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

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

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

{% 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
* **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 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
  {% 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-configuration.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.