CLI узла

На узле vStack OS администратору нужны две утилиты:

утилита кластера vstack-cluster показывает узлы и сервисы кластера, включает и отключает узлы, запускает, останавливает и переносит пулы;
скрипт обновления vStack.update.sh обновляет пакеты, базовую систему и ядро узла.

Обе запускаются от root на самом узле. Виртуальными машинами, сетями и ВЦОД управляет vStack Center, его интерфейс и API описаны в документации Center.

Утилита кластера

vstack-cluster — клиент Cluster Manager (демон ccrd). Приходит на узел вместе с пакетом vStack-ccrd и лежит в /usr/local/bin. Своего состояния у утилиты нет: каждая команда отправляется ccrd, а утилита печатает его ответ. Запускать её можно на любом узле кластера.

Формат вызова:

vstack-cluster <COMMAND> [<ACTION>] {OPTIONS}

Узел задаётся номером (--id, --dst-id), сервис — именем (-s, --service-name). Имя узла вместо номера утилита не принимает. Номер узла лежит в диапазоне 1–63.

Узлы и сервисы

Узел — сервер кластера. У него есть номер (Node ID) и имя вида q100u001.<домен>.
Сервис — то, что Cluster Manager размещает на одном из узлов. Каждый пул хранения zNN представлен сервисом zpool_zNN. Сервис cluster-management принадлежит самому Cluster Manager: вручную его не запускают, не останавливают и не переносят.

У узла и у сервиса по два независимых признака:

Признак	Значения	Смысл
`state`	узел: `ONLINE`, `OFFLINE`; сервис: `STARTED`, `STOPPED`, `STOPPING` и другие	фактическое состояние в данный момент
`[enabled]` / `[disabled]`	—	разрешено ли размещать на узле сервисы; участвует ли сервис в автоматическом размещении и переносе при отказе

Команды

Команда	Что делает
`status`	узлы и сервисы, которые на них работают
`node list`	номера узлов
`node status`	состояние всех узлов
`node disable --id=N`	закрыть узел для размещения сервисов
`node enable --id=N`	снова открыть узел
`service list`	имена сервисов
`service status`	состояние всех сервисов и узлы, на которых они работают
`service start -s <сервис> --id=N`	запустить сервис на узле `N`
`service stop -s <сервис>`	остановить сервис
`service move -s <сервис> --dst-id=N`	перенести сервис на узел `N`
`service enable -s <сервис>`	вернуть сервис в автоматическое размещение
`service disable -s <сервис>`	исключить сервис из автоматического размещения
`ha disk status`	состояние резервирований SCSI/NVMe на дисках группы фенсинга HA

Команда node exit выводит узел из кластера. Отменить её нельзя, поэтому здесь она не описана: выполняйте её только вместе с технической поддержкой vStack.

Общие опции

Опция	Что делает
`-h`, `--help`	справка текущего уровня, например `vstack-cluster service move --help`
`-v`, `--version`	версия утилиты
`-c <файл>`, `--config=<файл>`	другой файл конфигурации. Обычно не нужен

status

Узлы кластера и сервисы на каждом из них. С --json тот же состав выводится в JSON.

vstack-cluster status

Node ID:  1; name:   q100u001.example.com; state:       ONLINE; [     enabled]
	Service name:                zpool_z02; state:    STARTED; [     enabled]

Node ID:  2; name:   q100u002.example.com; state:       ONLINE; [     enabled]
	Service name:       cluster-management; state:    STARTED; [     enabled]
	Service name:                zpool_z03; state:    STARTED; [     enabled]

Node ID:  3; name:   q100u003.example.com; state:       ONLINE; [     enabled]

Node ID:  4; name:   q100u004.example.com; state:       ONLINE; [     enabled]
	Service name:                zpool_z01; state:    STARTED; [     enabled]
	Service name:                zpool_z04; state:    STARTED; [     enabled]

Если на узле нет ни одного сервиса, как у q100u003 в примере, это нормально для узла, который отказал и вернулся. Cluster Manager переносит пулы с упавшего узла, а обратно сам их не возвращает. Вернуть пул можно командой service move или из vStack Center.

vstack-cluster status --json

{
   "cluster": {
      "nodes": [
         { "enabled": true, "id": 1, "name": "q100u001.example.com", "state": "ONLINE" }
      ],
      "services": [
         { "enabled": true, "name": "zpool_z02", "nodeId": 1, "state": "STARTED" }
      ]
   }
}

services[].nodeId — номер узла, на котором работает сервис.

node list, node status

node list печатает только номера узлов, node status — номера, имена и состояние.

vstack-cluster node status

Node ID:  1; name:   q100u001.example.com; state:     ONLINE; [     enabled]
Node ID:  2; name:   q100u002.example.com; state:     ONLINE; [     enabled]

node disable, node enable

disable закрывает узел для размещения сервисов, enable открывает его снова.

vstack-cluster node disable --id=2
vstack-cluster node enable --id=2

предупреждение

После disable сервисы остаются на узле, и кажется, что команда ничего не делает. Но при следующем изменении состава кластера, например после перезагрузки любого узла, Cluster Manager пересчитывает размещение и уводит сервисы со всех закрытых узлов. Если открытым остался один узел, на него переедут все пулы кластера.

Закрывайте не больше одного узла за раз и открывайте его, как только закончили работы. Чтобы перенести пул, используйте service move, а не node disable.

service list, service status

service list печатает только имена сервисов. service status показывает состояние каждого и номер узла, на котором он работает.

vstack-cluster service status

Service name:       cluster-management; state:    STARTED at node:  2; [     enabled]
Service name:                zpool_z01; state:    STARTED at node:  4; [     enabled]
Service name:                zpool_z02; state:    STARTED at node:  1; [     enabled]

Выбрать один сервис или один узел в status нельзя, отфильтруйте вывод, например vstack-cluster service status | grep zpool_z01.

service start, service stop

stop останавливает сервис на узле, где он работает. start запускает остановленный сервис на указанном узле.

vstack-cluster service stop -s zpool_z03
vstack-cluster service start -s zpool_z03 --id=3

Остановка пул-сервиса означает экспорт пула: ВМ этого пула останавливаются, выдача его томов прекращается.

service move

Переносит сервис на другой узел. Исходный узел указывать не нужно.

vstack-cluster service move -s zpool_z01 --dst-id=2

Опция	Обязательна	Что задаёт
`-s`, `--service-name`	да	имя сервиса
`--dst-id`	да	номер узла назначения, 1–63

Узел назначения должен быть в ONLINE и открыт (enabled). На время переезда ВМ пула и выдача его томов прерываются. Пул, на котором работает управляющая ВМ (vStack Center), переносят только этой командой: из интерфейса Center его не перенести. Порядок действий — в разделе «Перенос пула с управляющей ВМ».

Если сервис остановился, а на новом узле не запустился, утилита не возвращает его обратно. Проверьте состояние командой service status и, пока сервис не в STARTED, обратитесь в техническую поддержку.

service enable, service disable

enable возвращает сервис в автоматическое размещение, disable исключает его оттуда.

vstack-cluster service enable -s zpool_z03

После enable Cluster Manager пересчитывает размещение и может сразу запустить сервис сам.

Коды возврата

Код	Значение
`0`	команда выполнена
`12`	неизвестная команда, неизвестная опция или не хватает обязательной опции. Утилита печатает причину и справку

ccrd_cli

Вместе с ccrd на узел ставится ccrd_cli. Без аргументов он печатает то же, что vstack-cluster status. Для работы с кластером используйте vstack-cluster.

vStack.update.sh

Скрипт обновления узла. Лежит в /root/bin/vStack.update.sh, обновляет пакеты из репозитория vStack: контроллеры, базовую систему и ядро. Порядок работ по обновлению, проверки и откат описаны на странице «Обновление узла до 3.2».

vStack.update.sh {--controllers | --base} [OPTIONS]

Пример

/root/bin/vStack.update.sh --controllers --base --source release --version 3.2.0 --dry-run

Что обновлять

Нужен хотя бы один из двух ключей, иначе скрипт завершится с кодом 1.

Ключ	Что обновляет
`--controllers`	пакеты узла, кроме базовой системы
`--base`	базовую систему и ядро, заодно и контроллеры. После него узел нужно перезагрузить

Откуда брать пакеты

Ключ	Значение	Что задаёт
`--source`	`release`	репозиторий релизов vStack. Для узлов заказчика это штатный источник. Нужен `--version`
`--source`	`local`	локальный репозиторий на узле, `file:///local/repos/vstack/...`
`--version`	`X.Y.Z` или `X.Y.Z-rcN`	версия поставки, например `3.2.0`
`--repo-url`	URL	другой адрес репозитория, например внутреннее зеркало

Доступ к репозиторию релизов выдаётся по списку разрешённых адресов. Адреса узлов для этого списка передайте в техническую поддержку vStack.

Как обновлять

Ключ	Что делает
`--dry-run`	показывает план и ничего не меняет
`--no-restart`	не перезапускает сервисы после обновления. Удобно, если следом идёт перезагрузка
`--reboot`	перезагружает узел после обновления базы и ядра. При кодах `6` и `7` игнорируется
`--log PATH`	путь к логу. По умолчанию `/var/log/vstack-os-update-<ts>.log`
`-h`, `--help`	справка

Защита загрузки

По умолчанию скрипт сохраняет прежнее ядро в <каталог ядра>_prev, один раз грузит новое с автооткатом на прежнее и обновляет загрузчик на EFI-разделе. Загрузчик копируется только на тот EFI-раздел, с которого узел загружен сейчас, на второй системный диск он не попадает.

Ключи ниже отключают эти защиты. Без указания поддержки их не используйте.

Ключ	Что отключает
`--no-kernel-backup`	копию прежнего ядра. Без неё скрипт не остановится, если под копию не хватает места
`--no-fallback`	одноразовую загрузку нового ядра с автооткатом
`--no-esp`	обновление загрузчика на EFI-разделе

Переход между мажорными версиями

Нужен только при переходе с линии 2.x на 3.x и выполняется вместе с технической поддержкой vStack.

Ключ	Что делает
`--allow-major-upgrade`	разрешает переход между мажорными версиями. Без него скрипт такой переход отклоняет с кодом `2`. На обычном обновлении внутри линии не нужен
`--install-missing`	доустанавливает все пакеты целевого релиза, которых нет на узле
`--rename-map PATH`	карта переименованных пакетов. По умолчанию берётся из поставки

Коды возврата

Код	Значение
`0`	обновление выполнено
`1`	ошибка в аргументах
`2`	источник или версия недоступны, не получен ключ подписи, либо переход между мажорами запрошен без `--allow-major-upgrade`
`3`	ошибка `pkg` или проверки нового ядра. Перезагрузки не будет
`4`	не удалось сохранить или восстановить конфигурацию: `/etc`, `/usr/local/etc`, `vstack-env.conf`, файлы загрузки в `/boot`
`5`	установленный сервис не перезапустился
`6`	обновление выполнено, но оболочка `root` не исполняема. Чинить до перезагрузки, иначе `root` не войдёт по ssh
`7`	обновление выполнено, но запись `/boot` не подтверждена. Не перезагружать до разбора

Файлы

Путь	Что там
`/var/backups/etc-<ts>/`	копия `/etc`, в подкаталогах `usr-local-etc` и `boot` копии `/usr/local/etc` и файлов `loader.conf`, `loader.conf.local`, `device.hints`. Хранятся пять последних
`/var/backups/vstack-env-<ts>.conf`	копия `vstack-env.conf`
`/var/backups/update-summary-<ts>.txt`	итоговая сводка прогона
`/var/log/vstack-os-update-<ts>.log`	полный лог
`/boot/nextboot.conf`, `/boot/loader.conf.d/zz-vstack-fallback.conf`	одноразовая загрузка нового ядра и откат. После успешной загрузки узел удаляет их сам

Утилита кластера​

Узлы и сервисы​

Команды​

Общие опции​

status​

node list, node status​

node disable, node enable​

service list, service status​

service start, service stop​

service move​

service enable, service disable​

Коды возврата​

ccrd_cli​

vStack.update.sh​

Пример​

Что обновлять​

Откуда брать пакеты​

Как обновлять​

Защита загрузки​

Переход между мажорными версиями​

Коды возврата​

Файлы​

Утилита кластера

Узлы и сервисы

Команды

Общие опции

status

node list, node status

node disable, node enable

service list, service status

service start, service stop

service move

service enable, service disable

Коды возврата

ccrd_cli

vStack.update.sh

Пример

Что обновлять

Откуда брать пакеты

Как обновлять

Защита загрузки

Переход между мажорными версиями

Коды возврата

Файлы