Административные команды CLI (yt admin)

Группа команд yt admin объединяет административные и диагностические утилиты для работы с кластером YTsaurus. Команды доступны через стандартный CLI-клиент yt (пакет ytsaurus-client).

Некоторым командам нужны дополнительные зависимости (kubernetes>=31.0.0 для logs k8s, docker>=7.1.0 для metrics replay). Они устанавливаются вместе с extra-набором admin:

export YT_SUPPRESS_ADMIN_EXPERIMENTAL_WARNING=1

Общий интерфейс

yt admin <admin_command> [<sub_command>] [options]

Список доступных подкоманд:

Получить справку по любой команде можно через --help:

yt admin --help
yt admin describe --help
yt admin describe cluster --help

Сменить лидера мастер-селла (switch-leader)

Переключает лидера указанного мастер-селла на заданный адрес.

yt admin switch-leader --cell-id <cell-id> --new-leader-address <address>

Пример

yt admin switch-leader \
  --cell-id 65726e65-ad6b7562-10259-79747361 \
  --new-leader-address ms-1.masters.ytsaurus-dev.svc.cluster.local:9010

Получить описание кластера или динамической таблицы (describe)

Собирает описание кластера или отдельных динамических таблиц (атрибуты, конфигурации, текущее состояние) и сохраняет его в файл.

Результат сохраняется в файл с временной меткой в имени, например describe/cluster_2026-06-03T12-00-00Z.yson.

Общие опции вывода для обеих подкоманд:

Описание кластера (cluster)

Собирает общую информацию о компонентах кластера и их конфигурации.

yt admin describe cluster [--nodes] [--bundles] [--dynamic-configs] [--static-configs] [-o dir] [--format ...]

Если не указан ни один из флагов --nodes, --bundles, --dynamic-configs, --static-configs, собирается вся информация сразу.

Примеры

Собрать информацию о кластере в YSON:

yt admin describe cluster

Собрать только информацию о нодах и бандлах в JSON в каталог debug:

yt admin describe cluster --nodes --bundles --format json -o debug

Описание динамических таблиц (table)

Собирает подробный набор атрибутов для одной или нескольких динамических таблиц, включая "тяжёлые" атрибуты (tablets, статистики по чанкам и сжатию). В качестве аргументов передаются один или несколько путей до динамических таблиц.

yt admin describe table <path> [<path> ...] [-o dir] [--format ...]

Пример

yt admin describe table //home/project/table1 //home/project/table2 --format yaml -o tables-dump

Выгрузить логи компонентов кластера (logs)

Выгружает логи компонентов кластера YTsaurus, развёрнутого в Kubernetes. Доступен единственный backend — k8s, работающий через Kubernetes API.

yt admin logs k8s [options] <cluster_name> <component_name> [<group_name>]

Утилита извлекает имена подов и пути к директориям из спецификации кластера, после чего находит нужные логи в контейнере ytserver. Далее она делает одно из двух:

• скачивает файлы логов целиком;
• выполняет grep на стороне сервера и сохраняет только те строки, которые совпали с запросом.

Требования

• Доступ к Kubernetes-кластеру (kubeconfig или in-cluster конфигурация).
• RBAC-права на get для CR ytsaurus и exec для подов в нужном namespace.
• Установленный python-пакет kubernetes (входит в ytsaurus-client[admin]).

Позиционные аргументы

Опции

Поддерживаемые компоненты

Имена подов строятся как <короткое_имя>-<группа>-<индекс> (часть -<группа>- опускается для группы default). Примеры: ms-0, rp-internal-0.

Примеры

Логи мастеров за интервал времени с двумя writer'ами:

yt admin logs k8s ytbench primary_masters \
  -w access -w debug \
  --from-ts 2026-02-07T14:38:01Z --to-ts 2026-02-07T14:48:01Z \
  -o case-1

Только конкретные поды:

yt admin logs k8s ytbench primary_masters -w debug \
  --from-ts 2026-02-07T14:38:01Z --to-ts 2026-02-07T14:48:01Z \
  -p ms-3 -p ms-4 -o case-1

Логи слота job-proxy на exec-ноде:

yt admin logs k8s ytbench exec_nodes -w debug \
  --from-ts 2026-02-07T14:38:01Z --to-ts 2026-02-07T14:48:01Z \
  --exec-slot-index 17 -p end-6 -o case-2

Серверный grep по содержимому:

yt admin logs k8s ytbench primary_masters -w debug --grep "Transaction aborted" -o case-3

Получить список доступных writer'ов компонента можно из его конфигурации в CR. Например, для primary_masters:

kubectl -n ytsaurus-dev get ytsaurus -o json | jq -r '
  .items[0].spec.primaryMasters |
  (.loggers[]? | select(.writerType == "file") | .name),
  (.structuredLoggers[]? | .name)
'

Структура вывода

<output_dir>/
  <pod_name>/
    <log_file>

Для слотов exec-нод:

<output_dir>/
  <pod_name>/
    slot/
      <slot_id>/
        <log_file>

Выгрузка и локальная визуализация метрик Prometheus (metrics)

Инструменты для работы с метриками: проверка спецификации выгрузки, выгрузка метрик из Prometheus в архив и воспроизведение архива локально через Prometheus + Grafana, которые разворачиваются локально в Docker.

yt admin metrics <validate|dump|replay> [options]

Формат spec.yaml

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

• defaults.step — шаг дискретизации по умолчанию (можно переопределить опцией --step).
• targets — список таргетов, каждый со своим type:
  • type: metric — задаёт PromQL-запрос в поле query; из запроса извлекаются селекторы.
  • type: dashboard — путь до JSON-файла дашборда Grafana в поле path (относительно spec.yaml); из всех панелей дашборда извлекаются expr. Значения переменных дашборда берутся из его templating и могут быть переопределены словарём params.

Пример spec.yaml:

defaults:
  step: 30s

targets:
  - type: metric
    query: yt_resource_tracker_total_cpu{service="master"}

  - type: dashboard
    path: master-accounts.json
    params:
      cluster: clusrer-name
      account: sys
      left_medium: default
      right_medium: ssd_blobs

В params указываются значения переменных дашборда. Если переменная не задана, берётся её значение по умолчанию из дашборда. Сам файл дашборда (поле path) можно получить из образа monitoring или собрать самостоятельно.

Селекторы из нескольких таргетов объединяются и дедуплицируются; посмотреть итоговый список можно командой metrics validate.

Дашборд для таргета type: dashboard

В поле path таргета type: dashboard указывается JSON-файл дашборда Grafana. Готовые собранные дашборды YTsaurus хранятся в репозитории — yt/admin/dashboards/yt_dashboards/tests_os/canondata. Оттуда нужный файл можно скачать напрямую и указать путь до него в path, например для дашборда master-accounts:

curl -O https://raw.githubusercontent.com/ytsaurus/ytsaurus/refs/heads/main/yt/admin/dashboards/yt_dashboards/tests_os/canondata/test_dashboards.test_master_accounts/master-accounts.json

Проверка спецификации метрик (validate)

Проверяет спецификацию метрик (spec.yaml) и печатает список уникальных селекторов.

yt admin metrics validate --spec spec.yaml [--target '<json>' ...]

Выгрузка метрик в архив (dump)

Выгружает метрики из Prometheus за заданный интервал в zip-архив.

yt admin metrics dump --spec spec.yaml \
  --from-ts <ISO8601> --to-ts <ISO8601> \
  --prometheus-url <url> [--step <step>] [--output metrics.zip] [--max-series N] [--force]

Локальное воспроизведение метрик (replay)

Импортирует метрики из ранее выгруженного архива во временную директорию и поднимает поверх неё локальные контейнеры Prometheus и Grafana для их просмотра.

yt admin metrics replay <archive.zip> [--prometheus-port N] [--grafana-port N]

Требования

• Доступ к docker-демону (контейнеры Prometheus и Grafana запускаются через него).
• Установленный python-пакет docker (входит в ytsaurus-client[admin]).

Пример сценария

# 1. Проверить спецификацию
yt admin metrics validate --spec spec.yaml

# 2. Выгрузить метрики за интервал (по умолчанию в metrics.zip)
yt admin metrics dump --spec spec.yaml \
  --from-ts 2026-06-03T10:00:00Z --to-ts 2026-06-03T11:00:00Z \
  --prometheus-url https://prometheus.example.com

# 3. Воспроизвести локально
yt admin metrics replay metrics.zip

Удалить нераспознанные опции из конфига мастера (remove-master-unrecognized-options)

Удаляет нераспознанные опции из динамического конфига мастера (//sys/@config).

Команда читает //sys/@master_alerts, находит алерт Found unrecognized options in dynamic cluster config и удаляет из //sys/@config все перечисленные в нём опции. После удаления вложенных опций пустые промежуточные узлы ({}) также удаляются. Если такого алерта нет, команда ничего не делает.

Чаще всего это требуется после обновления кластера: в новой версии YTsaurus часть полей конфига может выйти из употребления, и тогда они остаются в //sys/@config как нераспознанные.

yt admin remove-master-unrecognized-options [--dry] [--do-not-print-config]

Пример

# Посмотреть, какие опции будут удалены, ничего не меняя
yt admin remove-master-unrecognized-options --dry

# Удалить нераспознанные опции
yt admin remove-master-unrecognized-options

Запуск утилит как standalone-скриптов

Часть утилит дополнительно собрана как самостоятельные программы в каталоге yt/yt/scripts/. Они переиспользуют те же модули yt.admin.*, что и yt admin, и могут быть вызваны без установки полного CLI — например, в окружениях, где удобнее запускать модуль напрямую.