Инвентарь, метрики и контроль конфигурации ВМ

Методы этой страницы ничего не меняют. Они отвечают на четыре вопроса: какие ВМ есть в кластере, как устроена конкретная машина, что с ней происходило и как она себя чувствует сейчас. Отдельно стоит сверка конфигурации — она сравнивает работающую машину с эталоном, который держит vStack Center.

Область видимости у всех методов одна: роль Cluster master видит кластер целиком, остальные — только ВМ тех ВЦОД (виртуальных центров обработки данных), где им назначены роли.

В веб-интерфейсе тем же данным соответствуют список «All Virtual Machines» со столбцами «ID», «Name», «IP», «OS», «State», «Health», «vCPU class», «CPU (Cores)», «RAM (GB)», «Storage (GB)», поиск «Search in table» и выгрузка «CSV». На карточке ВМ живут секции «Perfdata» с переключателями «CPU», «Disks», «Networks», «Memory» и «Event history» со столбцами «ID», «Action», «Method», «Status», «Report», «Start Time», «End time», «Duration s».

Карточка ВМ: общие свойства, сети, диски, снимки, метрики и история событий

`vm-list`

Список ВМ. Доступ:

Cluster master — все ВМ кластера; в ответ добавляются поля node и rstart;
обычный пользователь — только ВМ из ВЦОД, где ему назначены роли; node и rstart не возвращаются.

Каждая машина приходит в ответе ровно один раз. До 3.1.1 машина повторялась столько раз, сколько у пользователя ролей в её ВЦОД, — внешние системы, строившие по этому списку свою инвентаризацию, получали дубликаты. Состав списка при исправлении не изменился, ушли только повторы.

Параметр	Тип	Обязателен	Описание
`objective`	любой	нет	Если поле присутствует с любым значением, ответ приходит картой по `vm_id` вместо массива
`vdc`	число	нет	Фильтр по ВЦОД, минимум `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
      }
    ]
  }
}

Что стоит знать о полях: address — IPv4-адрес первого порта (по наименьшему слоту) или null, если IPv4 не назначен; address_v6 — массив IPv6 того же порта, пустой массив при отсутствии адресов; nvme показывает режим дисков и тем самым определяет, где машину можно запускать.

Ошибка: -7 — сбой чтения списка.

`vm-get`

Полная карточка ВМ по идентификатору: основные поля, массивы network_ports и disks, объект hv_faults и, если доступны метрики, объект guest с потреблением памяти.

Параметр	Тип	Обязателен	Описание
`id`	число	да	Идентификатор ВМ, минимум `1`

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

Фрагмент ответа с устройствами:

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

Особенности формата, важные для клиентов API:

os_profile приходит строкой с UUID образа либо null. Короткий числовой идентификатор образа заменён на UUID в 3.0.5, это заявленное ломающее изменение;
GI_object, locked, create_completed, ip_guard, mac_guard сериализуются как 0, 1 или null;
pool — строка, root_dataset — число;
у диска sector_size.logical по умолчанию 512, physical — 4096;
объект guest присутствует, когда доступно хранилище метрик, даже если сами значения null; при недоступности метрик поле отсутствует.

Ошибки: -78 — сбой чтения, -3001 — ВМ не найдена в области видимости вызывающего.

`vm-statuses`

Справочник статусов ВМ: карта «код — имя». Параметров нет.

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

Используйте его, чтобы расшифровать числовые статусы из vm-list и vm-get в конкретном кластере. Ошибка: -7.

`vm-history`

История изменения статусов одной ВМ.

Параметр	Тип	Обязателен	По умолчанию	Ограничение
`vm_id`	число	да	—	минимум `1`
`lines`	число	нет	`50000`	допустимый диапазон `1..999`
`ts_start`	число	нет	`null`	не раньше `1531924200`
`ts_finish`	число	нет	`null`	не раньше `1531924200`, не позже `2222222222`, больше `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 }
    ]
  }
}

Фильтр по времени работает только когда переданы оба параметра диапазона. Без диапазона возвращаются последние записи с ограничением по lines.

Ошибки: -9305 — lines вне диапазона, -9320 и -9325 — слишком старые границы диапазона, -9326 — слишком большая верхняя граница, -9327 — ts_finish не больше ts_start, -7 — сбой чтения.

`vm-perfdata`

Метрики производительности ВМ. Доступ: Cluster master — любая ВМ; обычный пользователь — ВМ из ВЦОД, где у него роль с role_id ≤ 3.

Три режима:

Режим	Как вызвать	Что возвращает
Дашбордный	только `vm_id`	CPU, сеть, диск и RAM за последние 25 секунд
График за интервал	`metric` + `interval`	Ряд от текущего момента назад на `interval`
График за диапазон	`metric` + `begin_time` + `end_time`	Ряд по заданным границам

Параметр	Тип	По умолчанию	Ограничение
`vm_id`	число	—	обязателен, минимум `1`
`metric`	строка	`null`	`cpu`, `disk`, `net`, `ram`, `balloon`, `all`
`interval`	строка	`"1h"`	одна-две цифры и единица `s`, `m`, `h`, `d`, `w`
`slice`	строка	`"30s"`	одна-две цифры и единица `s`, `m`, `h` — шаг группировки
`begin_time`, `end_time`	число	`null`	10-значные отметки времени, работают только парой

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

Ответ хранилища метрик проксируется клиенту без преобразования, отметки времени — в секундах эпохи. Ошибки: -4930 — нет такой ВМ, -403 — нет роли в ВЦОД либо доступ запрещён, -4907, -4911, -4912, -4915, -4916 — некорректные metric, interval, slice, begin_time, end_time соответственно, -4925 и -4923 — сбой получения метрик.

`vm-check-configuration`

Сверяет конфигурацию работающей ВМ на гипервизоре с эталоном, который хранит vStack Center, и отдаёт компактный вердикт. Сырые данные гипервизора клиенту не передаются.

Привилегия — Check VM Configuration (1114), scope по ВЦОД. Выдана ролям Cluster master, администратор ВЦОД, пользователь ВЦОД и наблюдатель ВЦОД; роли Resource viewer метод отказывает ответом -403.

Параметр	Тип	Обязателен	Описание
`vm_id`	число	да	Идентификатор ВМ, минимум `1`

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

Вердикт совпадения:

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

При расхождении status равен mismatch, а mismatch_count показывает число разошедшихся ключей конфигурации. Сами имена и значения ключей в ответ и в журнал не попадают.

Что учитывать:

метод асинхронный: сначала приходит промежуточный ответ, финальный забирается через task;
ВМ обязана работать. У остановленной или приостановленной машины метод отвечает -4941 и не обращается к узлу;
успешный результат кешируется на 10 секунд по идентификатору ВМ: повторный вызов в этом окне вернёт тот же вердикт без обращения к узлу. Кеш сбрасывается после любой операции, меняющей конфигурацию ВМ;
часть ключей исключена из подсчёта расхождений — они меняются между запусками гипервизора, не меняя смысла конфигурации. Это префиксы gc., uefi.vars, pci.0.29.0.tcp и ключи с окончаниями .password, .secret, .key;
ответ агента больше 2000 ключей отбивается как слишком большой;
повторный вызов без изменений даёт тот же status и mismatch_count; обновляется только meta.fetched_at.

Ответ	Значение
`-403`	Нет привилегии либо ВМ вне scope роли
`-4940`	ВМ не существует или скрыта областью видимости
`-4941`	ВМ не работает
`-4942`	Узел ВМ недоступен
`-4943`	Агент узла не умеет отдавать конфигурацию во время работы
`-4944`	Ответ агента содержит слишком много ключей
`-4945`	Внутренняя ошибка сверки

Результат сверки попадает в журнал безопасности: событие о выполненной проверке пишется всегда, а при вердикте mismatch — дополнительно событие о нарушении целостности с уровнем alert. Событие о нарушении пишется только по свежему результату; вердикт, взятый из кеша, виден в событии о проверке.

`vm-inventory`

Инвентаризация ВМ кластера: vStack Center опрашивает агентов и сверяет собственные данные с тем, что видят узлы. Метод асинхронный, параметров нет, достаточно действующей сессии.

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

Как читать ответ: discrepancy — пары «сторона vStack Center — сторона узла». Пара [42, null] означает, что ВМ 42 есть в учёте кластера, но её не видит ни один агент; [null, 99] — обратный случай. Пустой массив означает отсутствие расхождений. VMs — карта «идентификатор ВМ — статус» по данным агентов. Служебные машины с идентификатором меньше 30 не учитываются.

Режим работы зависит от настройки кластера: при опросе по пулам ответ содержит discrepancy и VMs, при опросе по узлам этих полей нет. Ошибки: -200 — не удалось получить состояние узлов, -78 — сбой чтения.

См. также

Жизненный цикл виртуальной машины — что означают статусы и признаки hw_version, nvme, locked
Как создать, удалить и перенести виртуальную машину — справочник профилей ОС
Как управлять дисками и вычислительными ресурсами ВМ — справочник загрузочных носителей

vm-list​

vm-get​

vm-statuses​

vm-history​

vm-perfdata​

vm-check-configuration​

vm-inventory​

См. также​