Операции с Keeper

ClickHouse Keeper — критическая компонента кластера: без него останавливаются запись, DDL и репликация. Этот урок охватывает четыре практических аспекта операций с Keeper: мониторинг через 4-letter word команды, настройку learner-реплик для geo-распределения, миграцию с ZooKeeper, и восстановление после сбоев.

Мониторинг 4-letter word командами

Keeper поддерживает мониторинг через TCP-соединение по клиентскому порту 9181. Команды посылаются как четырёхбуквенные строки через nc (netcat):

# mntr: подробные метрики -- основная команда мониторинга
echo mntr | nc localhost 9181

Пример вывода:

zk_version              v23.8.1.1-ClickHouse-build
zk_avg_latency          0
zk_max_latency          15
zk_min_latency          0
zk_packets_received     1523421
zk_packets_sent         1523421
zk_num_alive_connections 2
zk_outstanding_requests 0
zk_server_state         leader
zk_znode_count          1247
zk_watch_count          89
zk_approximate_data_size 524288
zk_followers            2
zk_synced_followers     2

# stat: краткая статистика (режим, latency, connections)
echo stat | nc localhost 9181

# ruok: health check -- ответ "imok" означает работоспособность
echo ruok | nc localhost 9181
# Вывод: imok

# srvr: детальная информация о сервере (аналог stat, с версией)
echo srvr | nc localhost 9181

Ключевые метрики из mntr:

Learner replicas

Learner — это Keeper-узел, который участвует в репликации журнала, но не голосует в Raft-консенсусе и не может стать лидером. Learner-узлы полезны для geo-распределения и read-scaling без влияния на quorum.

Настройка learner через <can_become_leader>false</can_become_leader>:

<raft_configuration>
    <!-- Основной кластер: 3 голосующих узла (Raft quorum = 2 из 3) -->
    <server>
        <id>1</id>
        <hostname>keeper-01</hostname>
        <port>9234</port>
    </server>
    <server>
        <id>2</id>
        <hostname>keeper-02</hostname>
        <port>9234</port>
    </server>
    <server>
        <id>3</id>
        <hostname>keeper-03</hostname>
        <port>9234</port>
    </server>
    <!-- Learner в удалённом датацентре: replica только для чтения -->
    <server>
        <id>4</id>
        <hostname>keeper-04-dc2</hostname>
        <port>9234</port>
        <can_become_leader>false</can_become_leader>
    </server>
</raft_configuration>

Характеристики learner-реплики:

• Получает все записи журнала от лидера (fully replicated)
• Не участвует в голосовании — не нужен для формирования quorum
• Не может стать лидером — даже при сбое всех голосующих узлов
• Полезен для ClickHouse-серверов в DC2, которые могут читать метаданные из локального Keeper
• Не увеличивает latency write-операций (лидер не ждёт подтверждения от learner)

Миграция с ZooKeeper

Переход с ZooKeeper на ClickHouse Keeper — 5-шаговый процесс. Утилита clickhouse-keeper-converter конвертирует существующие данные ZooKeeper в формат Keeper.

Шаг 1: Остановить ingestion

# Остановить все INSERT-процессы и background merges
# На каждом ClickHouse-сервере:
SYSTEM STOP MERGES;
SYSTEM STOP FETCHES;

Это обеспечивает консистентное состояние ZooKeeper-снепшота перед миграцией.

Шаг 2: Конвертировать данные ZooKeeper

# clickhouse-keeper-converter читает ZooKeeper logs + snapshots
# и создаёт Keeper-совместимый снепшот
clickhouse-keeper-converter \
  --zookeeper-logs-dir /var/lib/zookeeper/log \
  --zookeeper-snapshots-dir /var/lib/zookeeper/data/version-2 \
  --output-dir /var/lib/clickhouse-keeper/

Утилита создаёт файлы снепшота в Keeper-формате. Данные включают: все пути znode (реплики, таблицы, DDL queue), текущий leader epoch, последний zxid.

Шаг 3: Скопировать снепшоты на все Keeper-узлы

# Скопировать снепшот на keeper-02 и keeper-03
scp -r /var/lib/clickhouse-keeper/ user@keeper-02:/var/lib/clickhouse-keeper/
scp -r /var/lib/clickhouse-keeper/ user@keeper-03:/var/lib/clickhouse-keeper/

Все три Keeper-узла должны начать с одинакового состояния.

Шаг 4: Обновить конфиг ClickHouse-серверов

<!-- Заменить ZooKeeper адреса на Keeper адреса в конфиге -->
<!-- Было: -->
<zookeeper>
    <node><host>zk-01</host><port>2181</port></node>
    <node><host>zk-02</host><port>2181</port></node>
    <node><host>zk-03</host><port>2181</port></node>
</zookeeper>

<!-- Стало: -->
<zookeeper>
    <node><host>keeper-01</host><port>9181</port></node>
    <node><host>keeper-02</host><port>9181</port></node>
    <node><host>keeper-03</host><port>9181</port></node>
</zookeeper>

Шаг 5: Запустить Keeper, затем ClickHouse

# Сначала запустить все Keeper-узлы
systemctl start clickhouse-keeper

# Проверить что Keeper кластер сформировался
echo srvr | nc keeper-01 9181 | grep Mode
# Ожидаем: Mode: leader (на одном узле), Mode: follower (на двух)

# Затем запустить ClickHouse-серверы
systemctl start clickhouse-server

После запуска возобновить merges и fetches:

SYSTEM START MERGES;
SYSTEM START FETCHES;

Восстановление реплик

При сбое Keeper или сети реплики могут перейти в ReadOnly или Broken состояние. Три команды для восстановления:

-- SYSTEM RESTORE REPLICA: полная пересинхронизация реплики
-- Сбрасывает локальные метаданные реплики в Keeper и перескачивает все части
-- Использовать когда реплика в Broken state или данные повреждены
SYSTEM RESTORE REPLICA table_name;

-- SYSTEM SYNC REPLICA: ожидание полной синхронизации
-- Блокирует выполнение до тех пор пока очередь репликации не опустеет
-- Использовать для проверки после восстановления или перед критическими операциями
SYSTEM SYNC REPLICA table_name;

-- Лёгкая версия: не ждёт слияния уже имеющихся частей
SYSTEM SYNC REPLICA table_name LIGHTWEIGHT;

-- SYSTEM DROP REPLICA: постоянное удаление реплики из Keeper
-- Удаляет все метаданные реплики из Keeper znode
-- Использовать для узлов которые больше не существуют
SYSTEM DROP REPLICA 'replica_name' FROM ZKPATH '/clickhouse/tables/01/db/table_name';

Диагностика перед восстановлением:

-- Проверить состояние реплик
SELECT
    database,
    table,
    replica_name,
    is_leader,
    is_readonly,
    total_replicas,
    active_replicas,
    queue_size,
    last_exception
FROM system.replicas
WHERE is_readonly = 1 OR last_exception != ''
ORDER BY database, table;

-- Проверить очередь репликации
SELECT
    database, table, type, create_time, last_exception
FROM system.replication_queue
WHERE last_exception != ''
ORDER BY create_time DESC
LIMIT 20;

Ключевые выводы

1. 4-letter word команды через порт 9181: mntr — подробные метрики (latency, role, connections), stat — кратко, ruok — health check.
2. Порты: 9181 = клиентский (4LW, ClickHouse подключения), 9234 = Raft internal (межузловой). Путаница — главная причина нерабочего кластера.
3. Learner replication через <can_become_leader>false</can_become_leader>: узел получает журнал, не голосует, полезен для geo-распределения и read-scaling без влияния на quorum.
4. Миграция с ZooKeeper: clickhouse-keeper-converter конвертирует ZK snapshots в Keeper-формат. 5 шагов: stop ingestion → convert → copy → update config → start Keeper, then ClickHouse.
5. Восстановление: SYSTEM RESTORE REPLICA (полная пересинхронизация), SYSTEM SYNC REPLICA (ожидание синхронизации), SYSTEM DROP REPLICA (постоянное удаление — необратимо).