Inventário de VMs, métricas e validação da configuração

Os métodos desta página não alteram nada. Eles respondem a quatro perguntas: quais VMs existem no cluster, como uma determinada VM está configurada, o que aconteceu com ela e como ela está agora. A validação da configuração é um caso à parte: ela compara a VM em execução com a configuração de referência mantida pelo vStack Center.

Todos os métodos têm o mesmo escopo de visibilidade: o papel Cluster master vê o cluster inteiro; os demais usuários veem apenas as VMs dos VDCs (data centers virtuais) em que têm papéis atribuídos.

Na interface web, os mesmos dados aparecem na lista All Virtual Machines, com as colunas ID, Name, IP, OS, State, Health, vCPU class, CPU (Cores), RAM (GB) e Storage (GB), a pesquisa Search in table e a exportação CSV. O cartão da VM tem uma seção Perfdata com as opções CPU, Disks, Networks e Memory, e uma seção Event history com as colunas ID, Action, Method, Status, Report, Start Time, End time e Duration s.

Cartão da VM: propriedades gerais, redes, discos, snapshots, métricas e histórico de eventos

`vm-list`

Lista de VMs. Acesso:

Cluster master: todas as VMs do cluster; a resposta inclui os campos adicionais node e rstart.
Um usuário comum: apenas as VMs dos VDCs em que tem papéis atribuídos; node e rstart não são retornados.

Cada VM aparece na resposta exatamente uma vez. Antes da versão 3.2.0, uma VM aparecia tantas vezes quantos fossem os papéis do usuário no VDC dela, de modo que sistemas externos que montavam inventários a partir dessa lista recebiam duplicatas. A correção não alterou quais VMs a lista contém; apenas removeu as duplicatas.

Parâmetro	Tipo	Obrigatório	Descrição
`objective`	Qualquer	Não	Se o campo estiver presente com qualquer valor, a resposta será um mapa indexado por `vm_id` em vez de um array
`vdc`	Número	Não	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
      }
    ]
  }
}

Detalhes dos campos: address é o endereço IPv4 da primeira porta (pelo menor slot), ou null se nenhum endereço IPv4 estiver atribuído; address_v6 é o array IPv6 dessa mesma porta, ou um array vazio se não houver endereços; nvme indica o modo de disco e, portanto, determina onde a VM pode ser iniciada.

Erro: -7 significa que não foi possível ler a lista.

`vm-get`

O cartão completo da VM por identificador: campos principais, os arrays network_ports e disks, o objeto hv_faults e, se as métricas estiverem disponíveis, um objeto guest com o uso de memória.

Parâmetro	Tipo	Obrigatório	Descrição
`id`	Número	Sim	Identificador da VM; mínimo `1`

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

Trecho da resposta com os 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
      }
    }
  }
}

Detalhes de formato relevantes para clientes da API:

os_profile é retornado como uma string com o UUID da imagem ou null. O identificador numérico curto da imagem foi substituído por um UUID na versão 3.0.5; trata-se de uma alteração incompatível declarada.
GI_object, locked, create_completed, ip_guard e mac_guard são serializados como 0, 1 ou null.
pool é uma string; root_dataset é um número.
Para um disco, sector_size.logical tem o padrão 512, e physical, o padrão 4096.
O objeto guest está presente quando o armazenamento de métricas está disponível, mesmo que os próprios valores sejam null; se as métricas estiverem indisponíveis, o campo não aparece.

Erros: -78 significa uma falha de leitura; -3001 significa que a VM não foi encontrada no escopo de visibilidade de quem fez a chamada.

`vm-statuses`

Referência de status de VM: um mapa de código para nome. Sem parâmetros.

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

Use-o para interpretar os status numéricos de vm-list e vm-get em um cluster específico. Erro: -7.

`vm-history`

Histórico de alterações de status de uma VM.

Parâmetro	Tipo	Obrigatório	Padrão	Limite
`vm_id`	Número	Sim	—	Mínimo `1`
`lines`	Número	Não	`50000`	Intervalo permitido `1..999`
`ts_start`	Número	Não	`null`	Não antes de `1531924200`
`ts_finish`	Número	Não	`null`	Não antes de `1531924200`, não depois de `2222222222`, maior 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 }
    ]
  }
}

A filtragem por tempo funciona apenas quando os dois parâmetros do intervalo são informados. Sem um intervalo, são retornados os registros mais recentes, limitados por lines.

Erros: -9305 significa que lines está fora do intervalo; -9320 e -9325 significam que os limites do intervalo são antigos demais; -9326 significa que o limite superior é grande demais; -9327 significa que ts_finish não é maior que ts_start; -7 significa uma falha de leitura.

`vm-perfdata`

Métricas de desempenho da VM. Acesso: o Cluster master pode acessar qualquer VM; um usuário comum pode acessar as VMs de um VDC em que tenha um papel com role_id ≤ 3.

Três modos:

Modo	Como chamar	Retorna
Painel	Apenas `vm_id`	CPU, rede, disco e RAM dos últimos 25 segundos
Gráfico por intervalo	`metric` + `interval`	Uma série que se estende do momento atual para trás pelo tempo de `interval`
Gráfico por faixa	`metric` + `begin_time` + `end_time`	Uma série dentro dos limites especificados

Parâmetro	Tipo	Padrão	Limite
`vm_id`	Número	—	Obrigatório; mínimo `1`
`metric`	String	`null`	`cpu`, `disk`, `net`, `ram`, `balloon`, `all`
`interval`	String	`"1h"`	Um ou dois dígitos e uma unidade: `s`, `m`, `h`, `d`, `w`
`slice`	String	`"30s"`	Um ou dois dígitos e uma unidade: `s`, `m`, `h`; o intervalo de agrupamento
`begin_time`, `end_time`	Número	`null`	Timestamps de 10 dígitos; usados apenas em par

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

A resposta do armazenamento de métricas é repassada ao cliente sem transformação; os timestamps estão em segundos epoch. Erros: -4930 significa que a VM não existe; -403 significa ausência de papel no VDC ou acesso negado; -4907, -4911, -4912, -4915 e -4916 significam metric, interval, slice, begin_time e end_time inválidos, respectivamente; -4925 e -4923 significam que a obtenção das métricas falhou.

`vm-check-configuration`

Compara a configuração da VM em execução no hipervisor com a configuração de referência armazenada pelo vStack Center e retorna um veredito conciso. Os dados brutos do hipervisor não são enviados ao cliente.

O privilégio é Check VM Configuration (1114), com escopo no VDC. Ele é atribuído aos papéis Cluster master, administrador do VDC, usuário do VDC e observador do VDC; o método rejeita o papel Resource viewer com -403.

Parâmetro	Tipo	Obrigatório	Descrição
`vm_id`	Número	Sim	Identificador da VM; mínimo `1`

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

Veredito de correspondência:

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

Em caso de divergência, status é mismatch, e mismatch_count mostra a quantidade de chaves de configuração que diferem. Os nomes e valores das chaves não são incluídos na resposta nem no log.

Tenha em mente o seguinte:

O método é assíncrono: primeiro chega uma resposta intermediária, e a resposta final é obtida por meio de task.
A VM precisa estar em execução. Para uma VM parada ou suspensa, o método retorna -4941 sem contatar o nó.
Um resultado bem-sucedido fica em cache por 10 segundos, por identificador de VM: outra chamada dentro dessa janela retorna o mesmo veredito sem contatar o nó. O cache é limpo após qualquer operação que altere a configuração da VM.
Algumas chaves são excluídas da contagem de divergências porque mudam entre inicializações do hipervisor sem alterar o significado da configuração. São os prefixos gc., uefi.vars, pci.0.29.0.tcp e as chaves terminadas em .password, .secret ou .key.
Uma resposta do agente com mais de 2000 chaves é rejeitada por ser grande demais.
Outra chamada sem alterações retorna os mesmos status e mismatch_count; apenas meta.fetched_at é atualizado.

Resposta	Significado
`-403`	Privilégio ausente, ou a VM está fora do escopo do papel
`-4940`	A VM não existe ou está oculta pelo escopo de visibilidade
`-4941`	A VM não está em execução
`-4942`	O nó da VM está indisponível
`-4943`	O agente do nó não consegue retornar a configuração enquanto a VM está em execução
`-4944`	A resposta do agente contém chaves demais
`-4945`	Erro interno de validação

O resultado da validação é registrado no log de segurança: um evento de verificação concluída é sempre registrado, e um veredito mismatch também gera um evento de violação de integridade no nível alert. O evento de violação é registrado apenas para um resultado novo; um veredito em cache aparece no evento de verificação.

`vm-inventory`

Inventário de VMs do cluster: o vStack Center consulta os agentes e compara os próprios dados com o que os nós veem. O método é assíncrono e não tem parâmetros; basta uma sessão ativa.

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

Como ler a resposta: discrepancy contém pares no formato "lado do vStack Center — lado do nó". O par [42, null] significa que a VM 42 está registrada no cluster, mas nenhum agente a vê; [null, 99] significa o inverso. Um array vazio significa que não há divergências. VMs é um mapa de identificador de VM para status, com base nos dados dos agentes. As VMs de serviço com identificadores abaixo de 30 são excluídas.

O modo depende da configuração do cluster: na consulta por pool, a resposta contém discrepancy e VMs; na consulta por nó, esses campos não aparecem. Erros: -200 significa que não foi possível obter os estados dos nós; -78 significa uma falha de leitura.

Veja também

Ciclo de vida da máquina virtual — o que significam os status e os atributos hw_version, nvme e locked
Como criar, excluir e mover uma máquina virtual — referência de perfis de SO
Como gerenciar os discos e os recursos computacionais da VM — referência de mídias de inicialização

vm-list​

vm-get​

vm-statuses​

vm-history​

vm-perfdata​

vm-check-configuration​

vm-inventory​

Veja também​