CLI admin commands (yt admin)

The yt admin command group combines the administrative and diagnostic utilities for working with a YTsaurus cluster. The commands are available through the standard yt CLI client (ytsaurus-client package).

Some commands require the additional dependencies (kubernetes>=31.0.0 for logs k8s, docker>=7.1.0 for metrics replay). These are installed together with the extra admin set:

export YT_SUPPRESS_ADMIN_EXPERIMENTAL_WARNING=1

Common interface

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

List of available subcommands:

Get help for any command with --help:

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

Switch the leader of a master cell (switch-leader)

Switches the leader of the specified master cell to a given address.

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

Example

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

Get a description of a cluster or dynamic table (describe)

Collects a description of the cluster or the individual dynamic tables (attributes, configurations, current state) and saves it to a file.

The result is saved to a file with a timestamp in its name, for example describe/cluster_2026-06-03T12-00-00Z.yson.

Common output options for both subcommands:

Cluster description (cluster)

Collects general information about cluster components and their configurations.

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

If none of the --nodes, --bundles, --dynamic-configs, --static-configs flags are specified, all information is collected at once.

Examples

Collect cluster information in YSON:

yt admin describe cluster

Collect only node and bundle information in JSON into the debug directory:

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

Dynamic table description (table)

Collects a detailed set of the attributes for one or more dynamic tables, including "heavy" attributes (tablets, chunk statistics, and the compression statistics). One or more paths to the dynamic tables are passed as arguments.

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

Example

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

Exporting logs of cluster components (logs)

Downloads logs of YTsaurus cluster components deployed in Kubernetes. Only one backend is available — k8s, which operates through the Kubernetes API.

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

The utility retrieves pod names and directory paths from the cluster specification, then finds the required logs in the ytserver container. It then does one of two things:

• Downloads entire log files.
• Runs grep on the server side and saves only the lines that match the query.

Requirements

• Access to a Kubernetes cluster (kubeconfig or in-cluster configuration).
• RBAC permissions for get on CR ytsaurus and exec on pods in the required namespace.
• Installed Python package kubernetes (included in ytsaurus-client[admin]).

Positional arguments

Options

Supported components

Pod names follow the pattern <short_name>-<group>-<index> (the -<group>- part is omitted for the default group). Examples: ms-0, rp-internal-0.

Examples

Master logs for a time interval with two writers:

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

Only specific pods:

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 slot logs on an exec node:

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

Server-side grep on content:

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

To get the list of available writers for a component, check its configuration in the CR. For example, for primary_masters:

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

Output structure

<output_dir>/
  <pod_name>/
    <log_file>

For exec node slots:

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

Export and local visualization of Prometheus metrics (metrics)

Tools for working with metrics: validating the export specification, exporting metrics from Prometheus to an archive, and replaying the archive locally using Prometheus + Grafana, which are deployed locally in Docker.

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

spec.yaml format

The specification describes which metrics to export. File structure:

• defaults.step — default sampling step (can be overridden with the --step option).
• targets — list of targets, each with its own type:
  • type: metric — specifies a PromQL query in the query field; selectors are extracted from the query.
  • type: dashboard — path to a Grafana dashboard JSON file in the path field (relative to spec.yaml); expr values are extracted from all dashboard panels. Dashboard variable values are taken from its templating and can be overridden with a params dict.

Example 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

The params field specifies dashboard variable values. If a variable is not set, its default value from the dashboard is used. You can get the dashboard file (the path field) from the monitoring image or build it yourself.

Selectors from multiple targets are merged and deduplicated; you can view the resulting list with the metrics validate command.

Dashboard for a type: dashboard target

The path field of a type: dashboard target specifies a Grafana dashboard JSON file. Pre-built YTsaurus dashboards are stored in the repository at yt/admin/dashboards/yt_dashboards/tests_os/canondata. You can download the required file directly from there and specify its path in path. For example, for the master-accounts dashboard:

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 the metrics specification (validate)

Validates the metrics specification (spec.yaml) and prints a list of unique selectors.

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

Export metrics to an archive (dump)

Exports metrics from Prometheus for a specified time range to a zip archive.

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]

Local replay of metrics (replay)

Imports metrics from a previously exported archive into a temporary directory and starts local Prometheus and Grafana containers on top of it for viewing.

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

Requirements

• Access to the docker daemon (Prometheus and Grafana containers are launched through it).
• The docker Python package installed (included in ytsaurus-client[admin]).

Example scenario

# 1. Validate the specification
yt admin metrics validate --spec spec.yaml

# 2. Export metrics for a time range (defaults to 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. Replay locally
yt admin metrics replay metrics.zip

Remove unrecognized options from the master config (remove-master-unrecognized-options)

Removes unrecognized options from the master dynamic config (//sys/@config).

The command reads //sys/@master_alerts, finds the alert Found unrecognized options in dynamic cluster config, and removes from //sys/@config all options listed in it. After removing nested options, empty intermediate nodes ({}) are also removed. If no such alert exists, the command does nothing.

This is most often needed after updating a cluster: in a new version of YTsaurus, some config fields may become obsolete and remain in //sys/@config as unrecognized.

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

Example

# View which options will be removed without making any changes
yt admin remove-master-unrecognized-options --dry

# Remove unrecognized options
yt admin remove-master-unrecognized-options

Running utilities as standalone scripts

Some utilities are additionally packaged as standalone programs in the yt/yt/scripts/ directory. They reuse the same yt.admin.* modules as yt admin and can be called without installing the full CLI — for example, in environments where it is more convenient to run a module directly.