Поля и коды ошибок методов хранения

Когда применять

Когда пишете интеграцию или разбираете ответ: нужно знать точный набор полей, тип параметра, уровень роли, границу ВЦОД (Виртуальный Центр Обработки Данных) и смысл кода ошибки. Пошаговые сценарии — в инструкциях по просмотру пулов и по свойствам датасета; модель — в «Пулы хранения».

Сводка группы

Метод	Режим	Параметры	Доступ	Что возвращает
pool-map	синхронный, из базы	нет	Cluster master, Resource Viewer	пулы, сгруппированные по node_id
pool-map-by-guid	синхронный, из базы	нет	в каноне API не указан	пулы, сгруппированные по guid, с ёмкостью
pools-list	асинхронный, ретрансляция	nodeId	Cluster master	пулы, обслуживаемые узлом, со свойствами ZFS
pools-get	асинхронный, ретрансляция	nodeId, name	Cluster master	полные свойства одного пула
filesystems-get	асинхронный, ретрансляция	guid	роль <= 2, свой ВЦОД	свойства датасета
filesystems-set	асинхронный, ретрансляция	guid, properties	роль <= 2, свой ВЦОД	обновлённые свойства датасета

Асинхронные методы отвечают дважды: промежуточным {"message": "relayed"} и финальным обратным вызовом от Storage-агента.

Методы

pool-map

Карта пулов кластера, сгруппированная по node_id — номеру обслуживающего узла. Параметров нет.

{"jsonrpc": "2.0", "method": "pool-map", "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

pool-map-by-guid

Детальная карта пулов кластера, сгруппированная по guid. Параметров нет.

{"jsonrpc": "2.0", "method": "pool-map-by-guid", "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

pools-list

Список пулов, которые обслуживает узел из nodeId.

Параметр	Тип	Обязательный	Ограничения
nodeId	number	да	диапазон 1–99

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

pools-get

Детальная информация о пуле, который обслуживает узел из nodeId.

Параметр	Тип	Обязательный	Ограничения
nodeId	number	да	диапазон 1–99
name	string	да	имя пула

{"jsonrpc": "2.0", "method": "pools-get", "params": {"nodeId": 5, "name": "pool-a"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

filesystems-get

Свойства файловой системы ZFS по GUID диска.

Параметр	Тип	Обязательный	Ограничения
guid	string | number	да	длина не меньше 1, числовое значение

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

filesystems-set

Изменение свойств файловой системы ZFS по GUID диска. Требует включённой фичи filesystem_options.

Параметр	Тип	Обязательный	Ограничения
guid	string | number	да	длина не меньше 1, числовое значение
properties	object	да	объект с изменяемыми свойствами ZFS

{"jsonrpc": "2.0", "method": "filesystems-set", "params": {"guid": "12345", "properties": {"compression": "zstd"}}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

Поля карты пулов

Оба метода карты отвечают из базы vStack Center. Наборы полей у них разные — колонка показывает, какой метод отдаёт поле.

Поле	pool-map	pool-map-by-guid	Смысл
guid	да	да	постоянный идентификатор пула
name	да	да	имя пула
health	да	да	состояние пула, у здорового ONLINE
consuming	да	да	пул принят кластером как рабочий носитель
capacity_pct	да	да	заполнение пула в процентах
size	да	да	полезная ёмкость, за вычетом доли избыточности
node_id	да	—	номер текущего обслуживающего узла пула
nodeid	—	да	то же поле без подчёркивания в имени
size_raw	—	да	сырая ёмкость, сумма дисков пула
used	—	да	занято данными
free	—	да	остаток полезной ёмкости
provisioned	—	да	сумма заявленных размеров датасетов пула
provisioned_pct	—	да	отношение provisioned к полезной ёмкости
scrubbing	—	да	идёт проверка целостности
resilvering	—	да	идёт восстановление избыточности
lif	—	да	сетевой адрес, по которому доступен пул

Разница в имени поля узла (node_id против nodeid) — свойство ответов, а не опечатка документации: клиент, разбирающий оба метода, должен знать оба имени.

Состав ответа живых методов

Пулы узла: pools-list

Ключ объекта data — имя пула. Поля записи:

allocated  capacity  checkpoint  comment  dedupditto  dedupratio  expandsize
fragmentation  freeing  guid  health  leaked  nodeId  readonly  size

Смысл ключевых полей: allocated — занято, capacity — заполнение в процентах, fragmentation — фрагментация в процентах, dedupratio — коэффициент дедупликации, expandsize — доступное расширение, readonly — режим только чтения, freeing — объём в процессе освобождения, leaked — потерянные блоки.

Свойства пула: pools-get

Объект data отдаёт полный набор свойств пула ZFS:

allocated  altroot  ashift  autoexpand  autoreplace  autotrim  bootfs  cachefile
capacity  checkpoint  comment  compatibility  consuming  dedupditto  dedupratio
delegation  expandsize  failmode  fragmentation  free  freeing  guid  health
leaked  listsnapshots  load_guid  maxblocksize  maxdnodesize  multihost  name
readonly  resilvering  scrubbing  size  tname  version

К полям карты здесь добавляются свойства самого пула: ashift — размер блока пула, autoexpand, autoreplace, autotrim — автоматические расширение, замена диска и TRIM, failmode — поведение при отказе, version — версия пула, load_guid — идентификатор текущей загрузки пула.

Свойства датасета: filesystems-get и filesystems-set

Ответ filesystems-get содержит fs_name — полное имя датасета вида pool-a/vm-100-disk-0 — и объект properties. В ответе filesystems-set диспетчер поле fs_name вырезает, остаётся только properties. Поле result.code тоже разное. У filesystems-get диспетчер проставляет 1, у filesystems-set код приходит от Storage-агента без изменений.

Состав properties:

available  checksum  compression  compressratio  context  copies  createtxg
creation  dedup  defcontext  encryption  fscontext  guid  inconsistent  keyformat
keylocation  logbias  logicalreferenced  logicalused  mlslabel  objsetid
pbkdf2iters  pbkdf2salt  primarycache  readonly  redacted  redundant_metadata
refcompressratio  referenced  refreservation  reservation  rootcontext
secondarycache  snapdev  snapshot_count  snapshot_limit  unique  used
usedbychildren  usedbydataset  usedbyrefreservation  usedbysnapshots
useraccounting  volblocksize  volsize  written

Поля, по которым чаще всего идёт разбор:

Поле	Смысл
volsize	заявленный размер тома — то, что видит гостевая система
volblocksize	размер блока тома
used	сколько датасет занимает в пуле сейчас
usedbydataset	из этого — доля самих данных
usedbysnapshots	из этого — доля, которую держат снимки
snapshot_count	число снимков датасета
snapshot_limit	предел числа снимков, -1 — без предела
logicalused	объём данных до сжатия
compression	алгоритм компрессии, например lz4 или zstd
compressratio	что дало сжатие
dedup	дедупликация датасета
encryption	шифрование датасета
available	доступный датасету остаток
readonly	режим только чтения
reservation	зарезервированный объём
refreservation	резерв под собственные данные датасета

Коды ошибок

Код	Сообщение	Методы	Что означает
-403	Access denied	все методы группы	уровня роли не хватает либо запрошен чужой ВЦОД
-21	ошибка базы	pool-map	диспетчер не прочитал карту из базы
-29	Unable to obtain pool map data	pool-map-by-guid	ошибка базы либо в кластере нет ни одного пула
-23	текст ошибки ретрансляции	pools-list	запрос не ушёл на узел
-24	nodeId is not present in the cluster	pools-list	узла с таким номером в кластере нет
-25	Pool is not present on the requested node	pools-list	узел ответил без данных о пулах
-33	текст ошибки ретрансляции	pools-get	запрос не ушёл на узел
-34	nodeId is not present in the cluster	pools-get	узла с таким номером в кластере нет
-35	Pool is not present on the requested node	pools-get	узел ответил без данных о пуле
-57	param guid has bad value	filesystems-get	негодный guid либо сбой ретрансляции
-58	Dataset does not exist at users scope	filesystems-get	датасета нет либо он принадлежит другому ВЦОД
-53	Unable to locate the dataset	filesystems-get	в базе диспетчера у строки датасета пусто имя
-54	Unable to locate the pool of the dataset	filesystems-get	пулу датасета не назначен обслуживающий узел
-86	param guid has bad value	filesystems-set	негодный guid либо сбой ретрансляции
-87	Filesystems methods has not been enabled	filesystems-set	фича filesystem_options в кластере выключена
-88	Dataset does not exist at users scope	filesystems-set	датасета нет либо он принадлежит другому ВЦОД
-83	Unable to locate the dataset	filesystems-set	в базе диспетчера у строки датасета пусто имя
-84	Unable to locate the pool of the dataset	filesystems-set	пулу датасета не назначен обслуживающий узел

Негодный nodeId отсекает валидатор параметров. Клиент получает -32602 Invalid params раньше, чем запрос дойдёт до обработчика метода.

Две пары кодов покрывают по два разных случая каждая: -57 и -86 — негодный guid и сбой ретрансляции; -58 и -88 — отсутствующий и чужой датасет. Последняя пара такова намеренно: существование датасета другого ВЦОД не раскрывается.

Соответствие колонок интерфейса

Таблица ZFS pools на табе Storage Resources повторяет поля карты пулов. Точную привязку колонок держит интерфейс; ниже — поле, которое несёт ту же величину.

Колонка	Поле карты
GUID	guid
Name	name
Health	health
Consuming	consuming
Scrubbing	scrubbing
Resilvering	resilvering
Current node	nodeid
Capacity (RAW)	size_raw и capacity_pct

Пример

Сквозной проход: снять карту, взять из неё пул, спуститься до свойств его датасета.

{"jsonrpc": "2.0", "method": "pool-map-by-guid", "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

Из ответа взяты "nodeid": 5 и "name": "pool-a". Запрашиваем свойства пула:

{"jsonrpc": "2.0", "method": "pools-get", "params": {"nodeId": 5, "name": "pool-a"}, "id": "cbf4478c-84b5-45ac-97cd-0390d7190585"}

Затем свойства датасета диска, лежащего в этом пуле:

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

Ожидаемо: в финальном ответе fs_name начинается с pool-a/ — датасет действительно лежит в запрошенном пуле.