Действия с дисками¶

Страница нужна инженеру эксплуатации, который добавляет, заменяет или выводит диски S3R на работающем кластере. Что такое диск S3R, его состояния и шаги описаны на странице Диски.

После первого запуска инстанса список дисков из конфигурации не читается: перечнем дисков служат строки таблицы s3r_disk. Диски добавляют, удаляют, признают вышедшими из строя и переформатируют действиями API управления либо кнопками на странице «Кластер» консоли.

Общее для всех действий:

нужна роль s3r_superuser;
действие записывается одной операцией «сравнить и заменить»;
действие вступает в силу на работающем инстансе без перезапуска.

Перечень действий¶

Действие	Запрос	Когда допустимо	Что происходит
Добавить диск	`POST /v2/disks` с телом `{"instance", "path", "tier", "failure_domain", "capacity_bytes"}`; поле `capacity_bytes` необязательно	см. Добавление диска. Допустимо и во время начального формирования	диск получает новый идентификатор; инстанс форматирует его, монтирует и переводит в состояние `active`
Удалить	`DELETE /v2/disks/{disk_id}`	ни одна группа размещения не числит диск участником: диск выведен, признан вышедшим из строя и заменён либо не входил в группы; у инстанса есть другой диск в этом ярусе	инстанс отключает диск и освобождает его директорию; строка удаляется, а поддомен остаётся свободным до добавления нового диска
Признать вышедшим из строя	`POST /v2/disks/{disk_id}/failed`	диск ещё не признан вышедшим из строя	диск переходит в состояние `failed`; владельцы его групп заменяют его участников, после начального формирования
Переформатировать	`POST /v2/disks/{disk_id}/reformat`, необязательное тело `{"path", "capacity_bytes"}`	диск в состоянии `failed`, `blank`, `foreign` или `corrupt`, его инстанс в кластере; новый путь не занят другим диском инстанса	диск сохраняет идентификатор и получает следующий номер форматирования; инстанс удаляет старые файлы экстентов, форматирует накопитель и монтирует его; группы сохраняют диск на прежнем месте и перестраивают его содержимое
Перевести в обслуживание	`POST /v2/disks/{disk_id}/drain`	после начального формирования; диск не вышел из строя	см. Замена исправного диска

Поле capacity_bytes задаёт ёмкость нового накопителя положительным числом байтов. Запрос, в котором оно задано иначе, отклоняется с ответом 400. Порядок, в котором определяется ёмкость нового накопителя, описан в разделе Ёмкость диска.

Ответ на действие¶

Исход	Ответ
действие выполнено	строка диска: идентификатор, инстанс, путь, ярус, поддомен, состояние, номер форматирования и признак ожидающего форматирования
нет такого диска или инстанса	`404`
действие недопустимо	`409` с причиной
неверный запрос	`400`

Добавление диска¶

Когда применять. На инстансе в ярусе есть свободный поддомен: например, диск раньше был удалён.

Новый поддомен добавить нельзя

Диск занимает только поддомен из шаблона яруса, свободный на этом инстансе: площадки должны оставаться симметричными.

Что должно быть выполнено заранее.

Поддомен из шаблона яруса свободен на инстансе.
Поддомен не содержит dc и компонентов домена отказа инстанса.
Путь не занят другим диском инстанса.
У инстанса задан слушатель s3r_storage.
Дисков в ярусе не станет больше 2 × (k + m) − 1. Схема берётся из записанной схемы избыточности яруса, а для яруса без записи — из s3r_storage.erasure.
Известна ёмкость нового диска. Она берётся из локального списка дисков инстанса, если там есть запись с тем же путём, иначе из поля capacity_bytes. Если не задано ни то, ни другое, в директорию диска должна быть смонтирована отдельная файловая система (см. Ёмкость диска).

Шаги.

Отправьте запрос. Пример для свободного поддомена hba=c:

curl -u ivanov -X POST https://console.example.net/s3gateway/api/v2/disks \
  -H 'content-type: application/json' \
  -d '{"instance": "default_1_1", "path": "/data/s3r/d2", "tier": "standard", "failure_domain": "hba=c"}'

Дождитесь, пока диск перейдёт в состояние active: его состояние и шаг показывают GET /v2/disks и страница «Кластер» консоли.

Результат. Новый диск используется для новых групп (см. Что не меняется при добавлении диска). Диск, добавленный перед сбоем инстанса, монтируется при его следующем запуске.

Замена вышедшего из строя накопителя¶

Когда применять. Накопитель неисправен и ещё не заменён.

Признайте диск вышедшим из строя (POST /v2/disks/{disk_id}/failed). Владельцы групп заменят его участников другими дисками.
Замените накопитель.
Переформатируйте диск (POST /v2/disks/{disk_id}/reformat), чтобы вернуть ёмкость. Если новый накопитель находится по другому пути или в его директорию не смонтирована собственная файловая система, укажите в теле запроса path и capacity_bytes.

Результат. Диск сохраняет идентификатор и после форматирования и монтирования возвращается в работу. Проверьте его состояние и шаг в ответе GET /v2/disks (см. также Проверка нового накопителя).

Накопитель заменён по тому же пути без действий в кластере¶

Признак. Диск переходит в состояние blank (новый накопитель без суперблока) или foreign (накопитель другого диска). Его участники удерживаются в группах.

Переформатируйте диск (POST /v2/disks/{disk_id}/reformat).

Результат. Группы перестраивают содержимое диска на месте, без смены состава.

Прежний накопитель

Прежний накопитель, вставленный после переформатирования, не принимается: его номер форматирования устарел.

Файловая система диска не смонтировалась при запуске¶

Признак. Диск переходит в состояние blank.

Смонтируйте файловую систему.

Результат. Следующая попытка монтирования находит суперблок диска и возвращает его в работу. Переформатировать диск не нужно.

Вывод исправного диска из эксплуатации¶

Переведите диск в обслуживание (POST /v2/disks/{disk_id}/drain; см. Замена исправного диска).
Дождитесь, пока ответ GET /v2/disks покажет для диска drained: true.
Удалите диск (DELETE /v2/disks/{disk_id}).

Если это последний диск инстанса в ярусе, удаление отклоняется: используйте следующую процедуру.

Замена исправного диска¶

Исправный диск перед извлечением переводят в обслуживание. Диск получает состояние draining: это вывод из работы, а не отказ. Диск продолжает отвечать на чтения, новые группы на нём не размещаются, а его фрагменты переносятся на другие диски той же площадки и того же яруса. Записи при этом не прекращаются.

Внимание

Отменить перевод в обслуживание нельзя, и в работу диск не возвращается. Накопитель можно снова использовать только как новый диск, добавленный действием «Добавить диск».
Диск нельзя извлекать, пока ответ GET /v2/disks не показывает drained: true. По составу групп этого не узнать: состав меняется сразу, а перестроение на новом участнике идёт после.
Помечать исправный диск состоянием failed не нужно. Это состояние означает отказ: данные восстанавливаются за счёт остальных дисков группы размещения, а не копируются.

Условия:

кластер прошёл начальное формирование. До него запрос отклоняется с ответом 409 и кодом ClusterNew, а неисправный диск признают вышедшим из строя и переформатируют;
диск не вышел из строя. Перевод вышедшего из строя диска отклоняется с ответом 409 и кодом DiskFailed.

Порядок действий:

Переведите диск в обслуживание запросом к API управления:
```
curl -u ivanov -X POST https://console.example.net/s3gateway/api/v2/disks/{диск}/drain
```
Повторный перевод диска в состоянии draining ничего не меняет.
Дождитесь, пока поле drained в ответе GET /v2/disks станет равным true. Это происходит, только когда на диске не осталось групп и группы площадки снова хранят все фрагменты:
```
curl -s -u ivanov "https://console.example.net/s3gateway/api/v2/disks?limit=1000" \
  | jq '.result.disks[] | select(.disk_id == "{диск}") | {state, drained}'
```
Группы, которые ещё перестраиваются, перечисляет GET /v2/repair/data в списке needs_resync, а их число показывает метрика s3r_resync_outstanding{kind="needs_resync"}.
Извлеките диск. Выведенный диск, которого больше нет ни в одной группе, удаляется действием «Удалить», если у его инстанса в ярусе есть другой диск (см. Действия с дисками).

Перезапуск инстанса перевод в обслуживание не отменяет. Выведенный диск возвращают в работу удалением и добавлением, а вышедший из строя — переформатированием.

Что происходит во время перевода¶

Участника каждой группы на выводимом диске заменяет владелец группы по правилам раздела «Группы не на своих позициях». Новым участником становится диск той же площадки и того же яруса в домене отказа, не занятом другими участниками, на котором свободных экстентов хватает на всё, что группа хранит на участнике.

Все группы диска переходят на новых участников сразу, поэтому переносить по одной группе за раз незачем.
Пока перестроение идёт, группы хранят на один фрагмент меньше, и скорость ограничена перестроением у владельца.
Пока на новом участнике не выделены экстенты группы, группа не выделяет новых позиций блоков. Если у владельца нет другой группы со свободным местом, запись в это время получает ответ 503 ServiceUnavailable и клиент повторяет её.
Участники групп в состоянии draining не заменяются.

Если перенос не завершается¶

Если подходящего диска нет, участник остаётся в группе. Он по-прежнему хранит свои фрагменты и отвечает на чтение, поэтому группа не считается деградированной. Пока данные не перенесены, перевод в обслуживание не завершается и диск извлекать нельзя. Замена повторяется, когда меняется состав дисков.

Где это видно:

в журнал владельца выводится предупреждение;
область groups ответа GET /v2/repair показывает группу в состоянии drain_waiting с важностью warning;
консоль показывает строку с причиной и действием, например «Нет места для переноса данных с диска {диск}: добавьте диск на площадке {площадка} в ярусе {ярус}» или «Не задана схема избыточности яруса: задайте её»;
ответ GET /v2/repair/groups содержит выводимый диск (disk_id), причину (cause) и действие, которое её устраняет (action).

`action`	Причина	Что сделать
`add_disk`	нет места для переноса данных: ни на одном подходящем диске нет места, или позиция плана занята вышедшим из строя, удалённым или выводимым диском	добавить диск на площадке и в ярусе группы
`add_instance`	нет инстанса в нужном домене отказа: в ярусе меньше инстансов или доменов отказа, чем требует его схема	добавить инстанс
`set_failure_domain`	не задан домен отказа дисков или инстансов	задать его
`set_shape`	не задана схема избыточности яруса	задать её
`wait`	подходящий диск или инстанс недоступен	ничего: перенос данных продолжится, когда он вернётся

Для оповещений подходят метрики (см. «Метрики»):

s3r_disks_drained — число выведенных дисков, которые можно извлечь;
s3r_drains_waiting — число участников на выводимых дисках, данные которых некуда перенести, по причинам;
s3r_extents.

Правила оповещения по s3r_drains_waiting в поставку не входят: администратор задаёт их в своей системе мониторинга.

Замена последнего диска инстанса в ярусе¶

Последний диск инстанса в ярусе действие «Удалить» не удаляет: без него инстанс выпал бы из раскладки яруса, и все следующие позиции сместились бы. Накопитель такого диска заменяют переформатированием.

Если диск исправен, признайте его вышедшим из строя: переформатирование допустимо только для диска в состоянии failed, blank, foreign или corrupt.
Замените накопитель.
Переформатируйте диск.

Проверка нового накопителя при переформатировании¶

Переформатирование проверяет новый накопитель до того, как что-либо на нём удалить. Если на накопителе помещается меньше экстентов, чем группы занимали на заменяемом накопителе:

накопитель не форматируется, файлы на нём остаются;
диск остаётся в состоянии new на шаге formatting;
в журнал инстанса выводится ошибка disk <id> at <путь> was not mounted: <путь> has room for N extents, and the groups that list disk <id> held M on the drive it replaces.

Что делать:

Поставить по тому же пути накопитель большего размера. Каждая следующая попытка монтирования повторяет форматирование, поэтому новых действий не требуется.
Задать другой путь или другое значение capacity_bytes. Признайте диск вышедшим из строя и переформатируйте его снова.

Восстановление размещения групп¶

Участников возвращает на место действие «Восстановить размещение»:

# Одна группа
curl -u ivanov -X POST https://console.example.net/s3gateway/api/v2/placement-groups/42/reform
# Все несимметричные группы площадки и яруса
curl -u ivanov -X POST https://console.example.net/s3gateway/api/v2/placement-groups/reform \
  -H 'content-type: application/json' -d '{"site": "default", "tier": "standard"}'

Действие доступно также в консоли: в разделе «Контроль целостности», в карточке «Группы» (кнопки «Восстановить размещение»).

Действие отклоняется с ответом 409:

Код	Когда
`RepairPaused`	фоновый контроль целостности приостановлен (`repair_mode = paused`). Восстановление размещения завершается только после ресинхронизации, а во время приостановки она не выполняется
`ClusterNew`	начальное формирование не завершено

Место под перенос не резервируется

За наличие места на дисках позиций плана отвечает администратор, запросивший восстановление размещения. Место заранее не резервируется, и замена не проверяет, изменился ли счётчик свободных экстентов диска после её решения. Если места не хватило, восстановление размещения можно запросить снова, когда оно появится.

Как выполняется действие:

Действие отмечает признаком reform_requested группы, несимметричные в этот момент, и отвечает их списком в поле requested. Группа, ставшая несимметричной позже, не отмечается.
Владелец отмеченной группы переносит участников по одному: переводит участника в состояние draining и заменяет его диском на позиции плана. Группа держит на один фрагмент меньше, пока перенесённый фрагмент не перестроен.
Старый диск освобождает экстенты группы. Только после этого переносится следующий участник, причём только пока все диски группы в состоянии active.

Перенос переживает перезапуск и смену владельца.

Владелец переносит участника, только если на диске позиции плана есть свободное место под все экстенты, которые занимает участник. Чем заканчивается перенос:

Что произошло	Результат
Группа вернулась на свои позиции	признак снимается
Места не хватает ни на одной из позиций, позиция перестала быть доступной или отказала в экстентах	участник остаётся на месте, признак снимается, причина записывается в журнал строкой `pg <N>: the re-form ends: ...` с числом свободных экстентов диска и нужным числом
Диск позиции временно недоступен: открывается или его инстанс перезапускается	решение откладывается до следующего шага процесса `group`

Что не меняется при добавлении и удалении дисков¶

Существующие группы. Новые диски используются для новых групп. Состав существующих групп при добавлении диска не меняется, и фрагменты между группами не переносятся (см. Ограничения). Это не относится к штатной перебалансировке шардов vshard: Picodata переносит строки метаданных между репликасетами, а обращение к метаданным повторяется при устаревшем маршруте.
Позиция удалённого диска. Удаляемый или вышедший из строя диск оставляет свою позицию в порядке позиций площадки. Новые группы ставят вместо неё другую позицию, и такие группы несимметричны (см. Группы не на своих позициях).
Разные диски в одном кластере. Диски разной ёмкости и разных типов используются одновременно, но в одном ярусе ёмкость дисков должна быть одинаковой. Участники группы получают место поровну, ёмкость диска при выборе участников не учитывается: проверяется только, что на диске есть свободные экстенты. Поэтому меньший диск заполняется первым. Его позиция получает причину position_full, инстанс, которому для новой группы нужен этот диск, сообщает в журнале needs a group and none can be formed и отклоняет запись, хотя на остальных дисках яруса место есть. Полезная ёмкость яруса определяется наименьшим диском. Тип носителя (NVMe, SSD или HDD) автоматически не определяется: администратор назначает диску ярус свойством tier=, а карта классов хранения направляет объекты в группы соответствующего яруса.