Inventario de VM, métricas y validación de la configuración

Los métodos de esta página no cambian nada. Responden a cuatro preguntas: qué VM existen en el clúster, cómo está configurada una VM concreta, qué le ha ocurrido y cómo se encuentra ahora. La validación de la configuración es aparte: compara la VM en ejecución con la configuración de referencia que mantiene vStack Center.

Todos los métodos tienen el mismo ámbito de visibilidad: el rol Cluster master ve todo el clúster; los demás usuarios solo ven las VM de los VDC (centros de datos virtuales) en los que tienen roles asignados.

En la interfaz web, los mismos datos aparecen en la lista All Virtual Machines con las columnas ID, Name, IP, OS, State, Health, vCPU class, CPU (Cores), RAM (GB) y Storage (GB), la búsqueda Search in table y la exportación CSV. La tarjeta de la VM tiene una sección Perfdata con los selectores CPU, Disks, Networks y Memory, y una sección Event history con las columnas ID, Action, Method, Status, Report, Start Time, End time y Duration s.

Tarjeta de la VM: propiedades generales, redes, discos, instantáneas, métricas e historial de eventos

`vm-list`

Lista de VM. Acceso:

Cluster master: todas las VM del clúster; la respuesta incluye los campos adicionales node y rstart.
Un usuario común: solo las VM de los VDC en los que tiene roles asignados; node y rstart no se devuelven.

Cada VM aparece en la respuesta exactamente una vez. Antes de la versión 3.2.0, una VM aparecía tantas veces como roles tenía el usuario en su VDC, por lo que los sistemas externos que construían inventarios a partir de esta lista recibían duplicados. La corrección no cambió qué VM contiene la lista; solo eliminó los duplicados.

Parámetro	Tipo	Obligatorio	Descripción
`objective`	Cualquiera	No	Si el campo está presente con cualquier valor, la respuesta es un mapa con clave `vm_id` en lugar de un array
`vdc`	Número	No	Filtro por VDC; mínimo `1`

{
  "jsonrpc": "2.0",
  "method": "vm-list",
  "params": {},
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

{
  "jsonrpc": "2.0",
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
  "result": {
    "code": 1,
    "data": [
      {
        "vdc_id": 2,
        "vm_id": 1,
        "vm_name": "vm-1",
        "vm_status": 3,
        "admin_status": 1,
        "oper_status": 3,
        "oper_status_ts": 1700000000,
        "os_type": 1,
        "os_profile": "8f14e45f-ceea-467a-9c1e-2d3b7a0f5c61",
        "cpu_count": 2,
        "memory_count": 1073741824,
        "hw_version": 3,
        "locked": 1,
        "create_completed": 1,
        "nvme": true,
        "storage_provisioned": 10737418240,
        "address": "192.0.2.1",
        "address_v6": ["2001:db8::10", "2001:db8::11"],
        "pool": "1000",
        "vcpu_class": 1,
        "service": 0,
        "GI_object": 0,
        "modified": 1700000000,
        "incarnation": 17000000000,
        "node": 5,
        "rstart": 0
      }
    ]
  }
}

Detalles de los campos: address es la dirección IPv4 del primer puerto (por la ranura más baja), o null si no hay ninguna dirección IPv4 asignada; address_v6 es el array IPv6 de ese mismo puerto, o un array vacío si no hay direcciones; nvme indica el modo de disco y, por tanto, determina dónde puede iniciarse la VM.

Error: -7 significa que no se pudo leer la lista.

`vm-get`

La tarjeta completa de la VM por identificador: campos principales, arrays network_ports y disks, el objeto hv_faults y, si hay métricas disponibles, un objeto guest con el uso de memoria.

Parámetro	Tipo	Obligatorio	Descripción
`id`	Número	Sí	Identificador de la VM; mínimo `1`

{
  "jsonrpc": "2.0",
  "method": "vm-get",
  "params": { "id": 42 },
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Fragmento de la respuesta con dispositivos:

{
  "jsonrpc": "2.0",
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
  "result": {
    "code": 1,
    "data": {
      "id": 42,
      "name": "vm-42",
      "cpus": 2,
      "ram": 1073741824,
      "hw_version": 4,
      "status": 3,
      "admin_status": 1,
      "oper_status": 3,
      "oper_status_ts": 1700000050,
      "locked": 0,
      "create_completed": 1,
      "nvme": true,
      "node": 3,
      "pool": "123456789",
      "root_dataset_name": "z01/.vm_V4/000000042",
      "vdc": 5,
      "network_ports": [
        {
          "network_id": 100,
          "port_id": 1,
          "address": "192.0.2.5",
          "address_v6": ["2001:db8::10"],
          "mac": "00:11:22:33:44:55",
          "ip_guard": 1,
          "mac_guard": 0,
          "ratelimit_mbits": 1000,
          "slot": 14
        }
      ],
      "disks": [
        {
          "guid": "111222333",
          "label": "data-disk",
          "size": 10737418240,
          "slot": 1,
          "iops_limit": 5000,
          "mbps_limit": 200,
          "sector_size": { "logical": 512, "physical": 4096 },
          "pool_name": "z01"
        }
      ],
      "guest": {
        "ram_used": 536870912,
        "ram_balloon_requested": null,
        "ram_balloon_performed": null
      }
    }
  }
}

Detalles del formato relevantes para los clientes de la API:

os_profile se devuelve como una cadena que contiene el UUID de la imagen o null. El identificador numérico corto de la imagen se sustituyó por un UUID en la versión 3.0.5; se trata de un cambio incompatible declarado.
GI_object, locked, create_completed, ip_guard y mac_guard se serializan como 0, 1 o null.
pool es una cadena; root_dataset es un número.
Para un disco, sector_size.logical tiene el valor predeterminado 512, y physical, 4096.
El objeto guest está presente cuando el almacén de métricas está disponible, aunque los propios valores sean null; si las métricas no están disponibles, el campo no aparece.

Errores: -78 significa un fallo de lectura; -3001 significa que la VM no se encontró dentro del ámbito de visibilidad del solicitante.

`vm-statuses`

Referencia de estados de VM: un mapa de código a nombre. Sin parámetros.

{
  "jsonrpc": "2.0",
  "method": "vm-statuses",
  "params": {},
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Úselo para interpretar los estados numéricos de vm-list y vm-get en un clúster concreto. Error: -7.

`vm-history`

Historial de cambios de estado de una VM.

Parámetro	Tipo	Obligatorio	Valor predeterminado	Límite
`vm_id`	Número	Sí	—	Mínimo `1`
`lines`	Número	No	`50000`	Intervalo permitido `1..999`
`ts_start`	Número	No	`null`	No anterior a `1531924200`
`ts_finish`	Número	No	`null`	No anterior a `1531924200`, no posterior a `2222222222`, mayor que `ts_start`

{
  "jsonrpc": "2.0",
  "method": "vm-history",
  "params": {
    "vm_id": 42,
    "lines": 100,
    "ts_start": 1700000000,
    "ts_finish": 1700100000
  },
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

{
  "jsonrpc": "2.0",
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
  "result": {
    "code": 1,
    "data": [
      { "ts": 1700000000, "ts_nano": 1700000000000000, "status": 3, "progress": 100 },
      { "ts": 1700000100, "ts_nano": 1700000100000000, "status": 5, "progress": 0 }
    ]
  }
}

El filtrado por tiempo solo funciona cuando se proporcionan ambos parámetros del intervalo. Sin intervalo, se devuelven los registros más recientes, limitados por lines.

Errores: -9305 significa que lines está fuera del intervalo; -9320 y -9325 significan que los límites del intervalo son demasiado antiguos; -9326 significa que el límite superior es demasiado grande; -9327 significa que ts_finish no es mayor que ts_start; -7 significa un fallo de lectura.

`vm-perfdata`

Métricas de rendimiento de la VM. Acceso: Cluster master puede acceder a cualquier VM; un usuario común puede acceder a las VM de un VDC en el que tenga un rol con role_id ≤ 3.

Tres modos:

Modo	Cómo invocarlo	Devuelve
Panel	Solo `vm_id`	CPU, red, disco y RAM de los últimos 25 segundos
Gráfico para un intervalo	`metric` + `interval`	Una serie que se extiende hacia atrás desde el momento actual durante `interval`
Gráfico para un rango	`metric` + `begin_time` + `end_time`	Una serie dentro de los límites especificados

Parámetro	Tipo	Valor predeterminado	Límite
`vm_id`	Número	—	Obligatorio; mínimo `1`
`metric`	Cadena	`null`	`cpu`, `disk`, `net`, `ram`, `balloon`, `all`
`interval`	Cadena	`"1h"`	Uno o dos dígitos y una unidad: `s`, `m`, `h`, `d`, `w`
`slice`	Cadena	`"30s"`	Uno o dos dígitos y una unidad: `s`, `m`, `h`; el intervalo de agrupación
`begin_time`, `end_time`	Número	`null`	Marcas de tiempo de 10 dígitos; solo se usan en pareja

{
  "jsonrpc": "2.0",
  "method": "vm-perfdata",
  "params": {
    "vm_id": 42,
    "metric": "cpu",
    "interval": "1h",
    "slice": "30s"
  },
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

{
  "jsonrpc": "2.0",
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
  "result": {
    "code": 1,
    "data": {
      "results": [
        {
          "statement_id": 0,
          "series": [
            {
              "name": "bhyve_cpu",
              "columns": ["time", "cpu", "vm_cpus"],
              "values": [[1700000030, 5.2, 4]]
            }
          ]
        }
      ]
    }
  }
}

La respuesta del almacén de métricas se transmite al cliente sin transformación; las marcas de tiempo están en segundos epoch. Errores: -4930 significa que no existe esa VM; -403 significa que no hay rol en el VDC o que se denegó el acceso; -4907, -4911, -4912, -4915 y -4916 significan valores no válidos de metric, interval, slice, begin_time y end_time, respectivamente; -4925 y -4923 significan que falló la obtención de métricas.

`vm-check-configuration`

Compara la configuración de la VM en ejecución en el hipervisor con la configuración de referencia almacenada por vStack Center y devuelve un veredicto conciso. Los datos sin procesar del hipervisor no se envían al cliente.

El privilegio es Check VM Configuration (1114), con ámbito de VDC. Está asignado a los roles Cluster master, VDC administrator, VDC user y VDC observer; el método rechaza el rol Resource viewer con -403.

Parámetro	Tipo	Obligatorio	Descripción
`vm_id`	Número	Sí	Identificador de la VM; mínimo `1`

{
  "jsonrpc": "2.0",
  "method": "vm-check-configuration",
  "params": { "vm_id": 42 },
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

Veredicto de coincidencia:

{
  "jsonrpc": "2.0",
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
  "result": {
    "code": 1,
    "data": {
      "status": "match",
      "mismatch_count": 0,
      "meta": { "fetched_at": 1780669931 }
    }
  }
}

En caso de discrepancia, status es mismatch y mismatch_count muestra el número de claves de configuración que difieren. Los nombres y valores de las claves no se incluyen en la respuesta ni en el registro.

Tenga en cuenta lo siguiente:

El método es asíncrono: primero llega una respuesta provisional, y la respuesta final se obtiene mediante task.
La VM debe estar en ejecución. Para una VM detenida o suspendida, el método devuelve -4941 sin contactar con el nodo.
Un resultado correcto se almacena en caché durante 10 segundos por identificador de VM: otra llamada dentro de esa ventana devuelve el mismo veredicto sin contactar con el nodo. La caché se borra tras cualquier operación que cambie la configuración de la VM.
Algunas claves se excluyen del recuento de discrepancias porque cambian entre inicios del hipervisor sin alterar el significado de la configuración. Son los prefijos gc., uefi.vars, pci.0.29.0.tcp y las claves que terminan en .password, .secret o .key.
Una respuesta del agente con más de 2000 claves se rechaza por ser demasiado grande.
Otra llamada sin cambios devuelve los mismos status y mismatch_count; solo se actualiza meta.fetched_at.

Respuesta	Significado
`-403`	Falta el privilegio, o la VM está fuera del ámbito del rol
`-4940`	La VM no existe o está oculta por el ámbito de visibilidad
`-4941`	La VM no está en ejecución
`-4942`	El nodo de la VM no está disponible
`-4943`	El agente del nodo no puede devolver la configuración mientras la VM está en ejecución
`-4944`	La respuesta del agente contiene demasiadas claves
`-4945`	Error interno de validación

El resultado de la validación se registra en el registro de seguridad: siempre se registra un evento de comprobación completada, y un veredicto mismatch genera además un evento de violación de integridad con el nivel alert. El evento de violación se registra solo para un resultado nuevo; un veredicto en caché aparece en el evento de comprobación.

`vm-inventory`

Inventario de VM del clúster: vStack Center consulta a los agentes y compara sus propios datos con lo que ven los nodos. El método es asíncrono y no tiene parámetros; basta con una sesión activa.

{
  "jsonrpc": "2.0",
  "method": "vm-inventory",
  "params": {},
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"
}

{
  "jsonrpc": "2.0",
  "id": "cbf4478c-84b5-45ac-97cd-0390d7190585",
  "result": {
    "code": 1,
    "data": {
      "discrepancy": [
        [42, null],
        [null, 99]
      ],
      "VMs": {
        "42": 3,
        "50": 1,
        "99": 5
      }
    }
  }
}

Cómo leer la respuesta: discrepancy contiene pares con la forma "lado de vStack Center — lado del nodo". El par [42, null] significa que la VM 42 está registrada en el clúster, pero ningún agente la ve; [null, 99] significa lo contrario. Un array vacío significa que no hay discrepancias. VMs es un mapa de identificador de VM a estado basado en los datos de los agentes. Las VM de servicio con identificadores inferiores a 30 se excluyen.

El modo depende de la configuración del clúster: cuando la consulta es por pool, la respuesta contiene discrepancy y VMs; cuando la consulta es por nodo, estos campos no aparecen. Errores: -200 significa que no se pudieron obtener los estados de los nodos; -78 significa un fallo de lectura.

Consulte también

Ciclo de vida de la máquina virtual: qué significan los estados y los atributos hw_version, nvme y locked
Cómo crear, eliminar y mover una máquina virtual: referencia de perfiles de SO
Cómo administrar los discos y los recursos de cómputo de una VM: referencia de medios de arranque

vm-list​

vm-get​

vm-statuses​

vm-history​

vm-perfdata​

vm-check-configuration​

vm-inventory​

Consulte también​