Расхождения, найденные при переписывании¶

При переписывании факты руководства не менялись. Всё, что расходится с кодом плагина, с другой страницей или само с собой, оставлено в формулировке руководства и собрано здесь. Код сверялся по сборке 26a730be. Каждый пункт нужно подтвердить или отклонить разработчикам плагина.

Может привести к ошибке оператора¶

/-/debug/rot доступен на уровне debug, а руководство относит его к bench. Эндпоинт намеренно портит фрагмент на диске и не требует аутентификации. Код: s3r/src/diag.rs, список путей уровня Bench в fn diagnostics. Страница: Диагностические эндпоинты.
Пример инвентарного файла Ansible со схемой 2+2 не пройдёт начальное формирование. В примере три сервера и по одному диску на инстанс без поддомена: доменов отказа дисков три, нужно четыре. Группа получит отказ not_enough_domains (crates/s3r-meta/src/placement/layout.rs, ветка Layout::Spread). Страница: Установка ролью Ansible.
Таблицы отказов говорят только о чтении. Для записи группе нужно k + m − write_tolerance участников. На переписанных страницах к таблицам добавлена оговорка.
Рекомендация «k + m + 1 доменов отказа» верна, только когда домен даёт группе одного участника. Страница об избыточности называет минимум (k + m) / m узлов, а пример одной площадки — три узла при схеме 2+2. Нужно точное правило.
Приостановка фонового контроля: три процесса или четыре. Раздел «Приостановка» называет scrub, resync, catalog; глоссарий и описание метрики s3r_repair_paused — ещё и resync_queue. Код подтверждает четыре (s3r/src/catalog.rs).
Ребутстрап инстанса не описан. По коду диски исключённого инстанса помечаются вышедшими из строя, а инстанс, занявший его позицию, переформатирует их (crates/s3r-meta/src/topology/departure.rs, disk_actions.rs). На странице Добавление, вывод и перезапуск узлов стоит предупреждение; процедуру нужно написать после прогона на стенде.
Действий оператора при отказе площадки в руководстве нет. На странице отказов это сказано прямо.
Шаг 6 установки проверяет сертификат по /etc/s3r/ca.pem, а в конфигурации шага 3 такого файла нет: там server.pem и cluster-ca.pem.

Противоречия внутри руководства¶

Состояние копии на площадке. «Пока в placements есть только одна запись live…» и «отдельного состояния у копии на площадке нет». Глоссарий разработчиков (doc/dev/GLOSSARY.md) на стороне второго.
Занимаемое место при широких схемах. Таблица «8+4 против трёх копий» (5 КиБ → 48 КиБ) посчитана с выравниванием 4 КиБ на фрагмент; соседний раздел говорит, что короткий фрагмент занимает малый блок 2 × inline_max = 8 КиБ, и тогда выходит 96 КиБ. В коде малый блок равен 2 * inline_max (crates/s3r-chunkstore/src/member/class.rs).
Секретный ключ. В описании API он «хранится в виде, из которого исходный ключ не восстанавливается», в справочнике таблиц «s3r_credential хранит секретные ключи».
Удаление тенанта через API. Таблица разделов API описывает /v2/tenants как «создание и удаление», справочник действий для удаления указывает «нет», в doc/api/openapi.yaml у маршрута только POST, PUT, GET.
/v2/health в описании API назван проверкой «живости», а по описанию консоли и коду это сводка по подсистемам. Требует роли s3r_superuser или s3r_observer (s3r/src/control/mod.rs).
/-/ready на шаге 6 установки описан полнее (группа в каждом ярусе, поля has_taken_groups и waiting), чем в справочнике эндпоинтов.
Параметр disks: «читается при запуске сервиса» и «один раз, при первом запуске».
Столбец тенанта: «тенант с заданным domain», а столбец называется fqdn (s3r/migrations/0001_namespace.sql).
Порты в примерах Ansible: 87<N>/84<N> в блоке plugins и 17<N>/80<N> в полном примере.
Имя архива s3r_2.2.0-astra_1.8_x86-64.tar.gz не соответствует шаблону s3r_<версия>-<ОС>.tar.gz.
Позиция при нескольких площадках. Руководство: «тот же репликасет и номер инстанса»; по комментарию к inherit_disks — тот же репликасет и тот же домен отказа.

Чего нет в руководстве, но есть в коде¶

Таблицы. В справочнике нет s3r_disk_free, s3r_catalog_pass, s3r_chunkgc, s3r_console_key и s3r_t<N>_resync, хотя первые две упоминаются на других страницах. «Таблицы блокового хранилища — по диску»: по миграциям они глобальные.
Роли. «Миграции создают три роли», а 0000_roles.sql создаёт шесть; s3r_metadata_reader в руководстве не упомянута.
Процесс chunkgc есть в коде и принимается в /-/debug/hold, в перечне фоновых процессов его нет.
Маршруты API, которых нет в таблице разделов: /v2/users/password, /v2/objects/delete, /v2/storage-classes, /v2/buckets/{bucket}/deduplication, /public-access, /v3/tenants, /v2/session.
Проверки значений. inline_max отклоняется также при нулевом и некратном значении; имя яруса ограничено [a-z0-9_-]{1,32}; api_memory = auto при неизвестном пределе памяти даёт 1 ГиБ; без s3_public_url и без FQDN тенанта операция отклоняется.
Сообщение журнала tier <ярус> records a geometry nothing can write в коде не найдено.
Аутентификация /metrics нигде не описана.
read_preference = any. На испытаниях два замера не показали выигрыша: чтения, которые инстанс не обслуживает сам, по-прежнему приходили на мастеров. При этом значение допускает устаревшие ответы, вплоть до действия отозванного разрешения. В руководстве параметр оставлен только в справочнике с пометкой «использовать не рекомендуется»; нужно решить, оставлять ли его вообще.
Диски разной ёмкости в одном ярусе. Ёмкость при выборе участников не учитывается (crates/s3r-meta/src/placement/layout.rs, проверяется только наличие свободных экстентов). На испытаниях меньший диск каждого сервера заполнился первым, и запись через его инстансы отклонялась (position_full) при 88 % заполнения кластера. В «Действиях с дисками» это теперь сказано; формулировку нужно подтвердить.

Мелочи¶

kernel-lt назван дважды в перечне ядер для РЕД ОС 7.3.
«Директории дисков очищаются отдельной операцией» при удалении плагина — какой, не сказано.
Упоминание заменённой метрики s3r_drain_stalled убрано как история; если оно нужно для старых правил оповещения, его надо вернуть.
Ограничение «не более 10 тегов» (MAX_TAGS) — применяется ли к тегам бакета, не проверено.
Команда изменения сертификата тенанта нигде не показана.

Что изменено по существу¶

Кроме перестройки текста, по результатам нагрузочных испытаний и разбора сделано следующее.

Убраны отладочные параметры backend и fs_root, раздел «Тестовый кластер» (cargo pike run), перечень эндпоинтов уровня bench и служебных эндпоинтов уровня debug. Вместо перечня — предупреждение и способ проверить, что уровень выключен.
Убраны следы прежних версий: вызов /v2/disks/{диск}/maintenance «для совместимости» и заметка о переименовании роли s3r_tenant_admin.
«10 логических ядер на инстанс» заменено правилом: число рабочих потоков и ещё два ядра.
В требования добавлен раздел «Сеть».
Из глоссария убраны общие статьи «Кэш», «Метаданные», «Квота», «Эндпоинт S3».
На начальную страницу вынесены шесть главных ограничений и таблица обозначений единого примера кластера; все команды и адреса в руководстве приведены к этому примеру.
В глоссарий добавлены 32 статьи, первое упоминание термина на каждой странице ведёт на его статью, термины Picodata — в глоссарий Picodata.
Для разработчика добавлены раздел «Гарантии согласованности» и страница «Ошибки и повторные запросы».
Вместо «оператор» и «администратор» везде «администратор».

Термины¶

Слово «позиция» означало две вещи. Теперь место диска в топологии называется «позиция», а место блока в экстентах группы — «позиция блока»; обе статьи есть в глоссарии. Развести нужно ещё слово «каталог»: в описаниях контроля целостности это строки объектов, а в названиях пула и таймаута catalog — изменения общих таблиц кластера через Raft. Статья глоссария называет оба значения; верно ли это разделение, нужно подтвердить.

При переписывании два процесса получили неверные русские названия («сверка позиций» у resync, «проверка чётности» у scrub); исправлено по таблице терминов плагина: «ресинхронизация» и «проверка целостности данных».

Числа, происхождение которых в руководстве не указано и по коду не установлено: 10 000 операций с метаданными в секунду на инстанс, около 320 байт памяти на объект, хранение сводки в кеше десять секунд. Нужно сказать, оценка это, измерение или константа.

Что переставлено после разрезки¶

При разрезке разделы остались на тех страницах, куда попали по порядку исходного текста. Затем они переставлены по назначению; ссылки на них исправлены, якоря прежние.

Раздел	Было	Стало
Замена исправного диска	«Наблюдение за кластером»	«Действия с дисками»
Восстановление размещения групп	«Группы размещения»	«Действия с дисками»
Начальное формирование	«Пошаговая установка»	отдельная страница в «Устройстве»
Если установка не завершается	«Пошаговая установка»	отдельная страница в «Установке»
Где хранятся данные	«Пошаговая установка»	«Устройство плагина»
Способы хранения, классы и ярусы	«Группы размещения»	отдельная страница в «Устройстве»
Выбор схемы избыточности яруса	«Группы размещения»	«Планирование топологии»
Ролевая модель тенантов	«Таблицы плагина»	«Тенанты»
Столбцы `s3r_tenant`, поля описания оборудования	«Создание и удаление тенанта»	«Таблицы плагина»
Правила CORS тенанта по умолчанию	«Управление доступом»	«Управление тенантами»
Как выполняются правила жизненного цикла, очистка после удаления бакета	«Настройки бакета»	«Фоновые процессы»
Запуск и приостановка фоновых процессов, расписание сверки каталога	«Фоновые процессы»	«Контроль целостности»
Ответы клиенту при отказе хранилища	«Отказы и восстановление»	«Ошибки и повторные запросы» в «Работе с S3»
Ключи и метаданные объекта	«Обращение к хранилищу»	«Операции с объектами»
Первый вход в консоль	«Консоль управления»	отдельная страница

Осталось на прежнем месте: включение дедупликации и сжатия описано на странице «Тенанты» в «Устройстве», хотя это действия администратора.