Диагностические эндпоинты и сетевые порты

Справочник для администратора кластера: какие служебные пути /-/ отвечают на порту S3, что каждый из них раскрывает или меняет, и какие сетевые порты использует плагин S3R и кому они должны быть доступны.

Диагностические эндпоинты

Аутентификации нет

Диагностические эндпоинты обслуживаются на порту S3 по путям, начинающимся с /-/, и подписи не требуют. Порт S3 обычно доступен клиентам, поэтому всё, что включено параметром s3r_api.diagnostics, доступно каждому, кто может обратиться к порту S3.

• Уровень debug раскрывает состав кластера, адреса узлов, план размещения и пути к дискам.
• Уровень bench выполняет ресурсоёмкие операции и открывает средства намеренного повреждения данных. Его следует применять только в изолированном испытательном контуре.

После диагностики верните уровень health (см. Как проверить действующий уровень).

Пути /-/ обслуживаются до проверки подписи, чтобы проверка наличия процесса работала и при ошибках аутентификации.

Уровни доступа

Набор доступных эндпоинтов задаётся параметром s3r_api.diagnostics:

Значение	Что доступно
health (по умолчанию)	только /-/health и /-/ready
debug	эндпоинты /-/debug/*, кроме средств внесения ошибок и повреждения данных
bench	все эндпоинты, включая /-/bench/* и средства внесения ошибок и повреждения данных

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

Ответы уровней debug и bench не являются интерфейсом мониторинга со стабильной схемой.

Как проверить действующий уровень

Обратитесь к любому эндпоинту уровня debug:

curl -s --cacert /etc/s3r/ca.pem https://node1.example.net:8443/-/debug/cluster

Если уровень равен health, ответ — 404 с полем "level":"health". Ответ 200 означает, что включён уровень debug или bench. Вернуть уровень по умолчанию:

ALTER PLUGIN s3r 2.2.0 SET s3r_api.diagnostics = 'health';

Новое значение действует сразу, без перезапуска.

В таблицах ниже столбец «Меняет состояние» показывает, изменяет ли обращение данные, схему или поведение инстанса. Аутентификация не требуется ни одному эндпоинту.

Уровень health

Путь	Аутентификация	Меняет состояние	Назначение
GET /-/health	нет	нет	проверка наличия процесса; готовность дисков, групп размещения и фоновых процессов не проверяется
GET /-/ready	нет	нет	готовность, см. Ответ /-/ready

Ответ /-/ready

Состояние	Ответ
кластер прошёл начальное формирование, а инстанс загрузил свои группы размещения	200 и {"status":"ready"}
иначе	503 с состоянием кластера в поле status, шагом формирования в поле step и причинами в поле waiting

После формирования состояние дисков на ответ не влияет.

Уровень debug

Сведения о кластере:

Путь	Аутентификация	Меняет состояние	Назначение
/-/debug/cluster	нет	нет	состав кластера: инстансы, пригодные для размещения данных
/-/debug/peers	нет	нет	адреса обмена фрагментами из таблицы _pico_peer_address
/-/debug/replicasets	нет	нет	репликасеты тира Picodata, их состав и фактор репликации
/-/debug/topology	нет	нет	первые группы размещения, которые были бы созданы, и причины, по которым кластер не формируется; параметры k, m, tier и stripe_bytes заменяют схему избыточности яруса. См. Проверка топологии

Сведения об инстансе, к которому обращён запрос:

Путь	Аутентификация	Меняет состояние	Назначение
/-/debug/disks	нет	нет	диски данного инстанса, их ярус, ёмкость и число свободных экстентов. См. Занятость диска
/-/debug/repair	нет	нет	что перестроению осталось исправить на данном инстансе
/-/debug/group	нет	нет	группы размещения, которыми владеет данный инстанс: готова ли группа принимать запись, число объектов, а по каждому классу блоков курсор, свободные блоки и предел из строки группы; с параметром object только блоки указанного объекта в этих группах
/-/debug/state	нет	нет	дерево состояния данного инстанса, см. Ответ /-/debug/state
/-/debug/catalog	нет	нет	отчёт о проверке строк каталога, которыми владеет репликасет данного инстанса: найденные расхождения и то, что можно восстановить. Проверку выполняет только мастер репликасета; реплика возвращает пустой отчёт с полем "master": false
/-/debug/quota	нет	нет	распределение долей ограничений скорости на данном инстансе
/-/debug/admission	нет	нет	общий объём памяти api_memory, свободная и занятая части, а также действующие значения read_timeout_s, write_timeout_s и catalog_timeout_s
/-/debug/workers	нет	нет	число запущенных и ожидающих очереди циклов каждого фонового процесса на данном инстансе; в обычном режиме у процесса один цикл запущен и ни один не ждёт

Управление фоновыми процессами:

Путь	Аутентификация	Меняет состояние	Назначение
/-/debug/run/<процесс>	нет	да: выполняет работу процесса	немедленное выполнение одного шага фонового процесса; параметр mode выбирает вариант шага, параметр steps задаёт число шагов подряд
/-/debug/hold/<процесс>	нет	да: процесс не работает	приостановка фонового процесса на данном инстансе
/-/debug/release/<процесс>	нет	да	возобновление приостановленного фонового процесса

Ответ /-/debug/state

Дерево состояния — копия глобальных таблиц плагина и Picodata, которую инстанс обновляет после каждой применённой записи журнала Raft.

Поле	Значение
ready	признак готовности. Пока он равен false, запросы S3 получают ответ 503
ags_index	номер последней учтённой записи журнала
rows	число строк каждой таблицы

Параметр detail добавляет номера групп размещения с их эпохами и классы ярусов.

Проверка топологии

Проверка возможности собрать группу по схеме 8+4 в текущей топологии:

curl -s --cacert /etc/s3r/ca.pem "https://node1.example.net:8443/-/debug/topology?k=8&m=4&tier=standard"

Поля ответа:

Поле	Значение
state	состояние кластера
step	шаг формирования
can_form	признак готовности к формированию
problems	найденные проблемы
would_form	первые группы, которые были бы сформированы, с их раскладкой
refusals_count	число причин отказа
reasons	причины отказа, см. Раскладка группы
tiers	сводка по каждому ярусу

Занятость диска

Эндпоинт /-/debug/disks сообщает только о дисках того инстанса, к которому обращён запрос.

Занятость диска считается по экстентам:

• столбец free_extents таблицы s3r_disk_free содержит размер свободного пула, каким его подсчитал сам диск;
• занятое место равно extent_count - free_extents, умноженному на размер экстента.

Диск записывает это число не при каждом изменении, а когда с последней записи оно сдвинулось на процент от числа экстентов диска. В последнем проценте, то есть на почти заполненном диске, записывается каждое изменение. Поэтому столбец и метрика s3r_extents точны до процента диска, а нулевое число свободных экстентов отражается сразу.

Уровень bench

Только для автоматизированных испытаний

Уровень bench открывает эндпоинты, которые вносят ошибки в обработку запросов, сдвигают часы, запускают встроенный генератор нагрузки, удаляют и намеренно повреждают фрагменты на дисках, меняют участников групп и схему таблиц. Аутентификации они не требуют. На кластере с данными уровень bench не включают.

Эти эндпоинты предназначены для испытаний плагина его разработчиками и в руководстве не описываются.

Сетевые порты

Внимание

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

Порт	Чем задаётся	Что обслуживает	Кому должен быть доступен
Порт эндпоинта S3	instance.plugin.s3r.service.s3r_api.listener либо S3R_API_LISTEN	эндпоинт S3; диагностика плагина по путям /-/	клиентам S3; браузеру администратора — по адресу из s3r_api.s3_public_url либо FQDN тенанта
Порт обмена фрагментами	instance.plugin.s3r.service.s3r_storage.listener	обмен фрагментами полос между узлами по протоколу HTTP/2	только узлам кластера
HTTP-порт Picodata	instance.http_listen	веб-интерфейс Picodata, консоль и API управления S3R, метрики /metrics	браузеру администратора

Браузеру администратора нужен доступ к двум портам: консоль загружает и скачивает файлы по заранее подписанным ссылкам напрямую через эндпоинт S3.

Параметры слушателей описаны в разделе Конфигурация Picodata.