ClickHouse Keeper

ClickHouse Keeper представляет собой полнофункциональную замену Apache ZooKeeper, разработанную специально для координации и управления кластерами ClickHouse^®. Решение обеспечивает полную совместимость с клиентским протоколом ZooKeeper и использует ту же модель данных, предлагая при этом значительные улучшения в производительности и функциональности.

Упрощенная установка и эксплуатация

• Реализован на языке C++ вместо Java, что обеспечивает более эффективное использование ресурсов
• Может работать как встроенным в ClickHouse^®, так и в автономном режиме.
• Использует меньше памяти для того же объема данных по сравнению с ZooKeeper.

Оптимизированное хранение данных

• Снимки состояния и логи занимают значительно меньше дискового пространства благодаря улучшенному сжатию.
• Отсутствует ограничение на размер пакета и данных узла по умолчанию — в ZooKeeper ограничение составляет 1 МБ.
• Нет проблемы переполнения ZXID, которая в ZooKeeper требует перезапуска каждые 2 миллиарда транзакций.

Повышенная производительность и надежность

• Более быстрое восстановление после сетевых разделений благодаря использованию улучшенного протокола распределенного консенсуса.
• Дополнительные гарантии консистентности: обеспечивает те же гарантии консистентности, что и ZooKeeper — линеаризуемые записи и строгий порядок операций в рамках одной сессии.
• Опционально предоставляет линеаризуемые чтения через настройку quorum_reads.

Ключевые функции координации

ClickHouse Keeper выполняет критически важные функции в экосистеме ClickHouse^®:

• Обеспечивает систему координации для репликации данных в самоуправляемых кластерах ClickHouse^®.
• Осуществляет автоматическую дедупликацию вставок для реплицируемых таблиц семейства движков MergeTree на основе хеш-сумм блоков.
• Предоставляет консенсус относительно имен частей, назначения слияний частей и мутаций конкретным узлам кластера.
• Используется движком таблиц KeeperMap, который позволяет использовать Keeper как консистентное хранилище «ключ-значение».
• Отслеживает обработанные файлы в движке таблиц S3Queue.
• Хранит все метаданные движка Replicated Database.
• Координирует создание резервных копий с использованием конструкции ON CLUSTER.
• Служит хранилищем для пользовательских функций и информации контроля доступа.
• Используется как общее центральное хранилище для всех метаданных в ClickHouse Cloud.

ClickHouse Keeper представляет собой надежное и эффективное решение для координации распределенных систем, специально оптимизированное для работы с ClickHouse^®.

1. Создайте облачную сеть и подсеть, в которой будет находиться виртуальная машина (ВМ).

2. Создайте группу безопасности для ВМ vm-keeper в созданной облачной сети и настройте правила:

   Направление трафика	Описание	Диапазон портов	Протокол	Источник / Назначение	CIDR-блоки
   Входящий	CH Keeper	9181	TCP	CIDR	0.0.0.0/0
   Входящий	SSH	22	TCP	CIDR	0.0.0.0/0
   Исходящий	Any Egress	0-65535	Any	CIDR	0.0.0.0/0

3. Создайте группу безопасности для ВМ vm-test в той же сети и настройте правила:

   Направление трафика	Описание	Диапазон портов	Протокол	Источник / Назначение	CIDR-блоки
   Входящий	HTTP	80	TCP	CIDR	0.0.0.0/0
   Входящий	SSH	22	TCP	CIDR	0.0.0.0/0
   Исходящий	Any Egress	0-65535	Any	CIDR	0.0.0.0/0

4. Получите пару SSH-ключей для подключения к ВМ.

5. Установите и настройте приложение.

   1. В Marketplace найдите продукт ClickHouse Keeper и нажмите Создать ВМ.

      1. В блоке Сетевые настройки укажите облачную сеть, подсеть и группу безопасности для ВМ vm-keeper, созданные ранее.

      2. В блоке Доступ укажите имя пользователя и публичный SSH-ключ для подключения к ВМ.

      3. В блоке Общая информация укажите имя ВМ — vm-keeper.

      4. Завершите создание ВМ и нажмите Создать ВМ.

         Дождитесь создания ВМ и установки приложения — это может занять 10 минут.

   2. Узнайте публичный IP-адрес ВМ vm-keeper.

   3. Подключитесь к ВМ vm-keeper по SSH. Для этого используйте имя пользователя, которое вы задали при создании ВМ, и закрытый SSH-ключ, созданный ранее.

   4. Добавьте в файл /etc/clickhouse-keeper/keeper_config.xml сразу после строки <clickhouse>:

      <listen_host>0.0.0.0</listen_host>
      

      В продакшн-среде не рекомендуется использовать адрес 0.0.0.0.

   5. Проверьте, что ClickHouse Keeper запущен:

      sudo systemctl status clickhouse-keeper
      

      Результат:

      ● clickhouse-keeper.service - ClickHouse Keeper - zookeeper compatible distributed coordination server
          Loaded: loaded (/usr/lib/systemd/system/clickhouse-keeper.service; enabled; preset: enabled)
          Active: active (running) since Wed 2026-03-04 19:15:51 UTC; 17min ago
      ...
      

      Если ClickHouse Keeper не запустился, запустите его вручную, выполнив команду:

      sudo systemctl start clickhouse-keeper
      

6. Создайте и настройте ВМ для тестирования работы ClickHouse Keeper.

   1. При создании ВМ укажите параметры:

      1. В блоке Образ загрузочного диска на вкладке Marketplace выберите образ Ubuntu или Debian, например Ubuntu 24.04.
      2. В блоке Сетевые настройки укажите облачную сеть, подсеть и группу безопасности для ВМ vm-test, созданные ранее.
      3. В блоке Доступ укажите имя пользователя и публичный SSH-ключ для подключения к ВМ.
      4. В блоке Общая информация укажите имя ВМ — vm-test.

   2. Узнайте публичный IP-адрес ВМ vm-test.

   3. Подключитесь к ВМ vm-test по SSH. Для этого используйте имя пользователя, которое вы задали при создании ВМ, и закрытый SSH-ключ, созданный ранее.

   4. Установите ClickHouse Server и ClickHouse Client, выполнив инструкцию Install ClickHouse on Debian/Ubuntu.

   5. Создайте файл /etc/clickhouse-server/config.d/zookeeper.xml и добавьте в него следующий код:

      <clickhouse>
          <zookeeper>
              <node>
                  <host>публичный_IP-адрес_ВМ</host>
                  <port>9181</port>
              </node>
          </zookeeper>
      </clickhouse>
      

      В поле host укажите публичный IP-адрес vm-keeper.

   6. Запустите сервер, выполнив команду:

      sudo systemctl start clickhouse-server
      

   7. Включите режим выполнения SQL-запросов, выполнив команду:

      clickhouse-client
      

   8. Выполните запрос:

      SELECT
          hostname() AS clickhouse_server,
          zookeeperSessionUptime() AS keeper_session_seconds
      

      Результат:

      Query id: 040b6642-faf0-4a2b-9c79-50bb********
         ┌─clickhouse_server─┬─keeper_session_seconds─┐
      1. │ vm-test           │                    158 │
         └───────────────────┴────────────────────────┘
      1 row in set. Elapsed: 0.002 sec.
      

7. Проверьте соединение.

   1. Подключитесь к ВМ vm-keeper по SSH.

   2. Выполните команду:

      sudo ss -anp | grep :9181
      

      Результат:

      tcp   LISTEN 0   64   *:9181   *:*   users:(("clickhouse-keep",pid=806,fd=42))
      tcp   ESTAB  0   0    [::ffff:10.0.0.30]:9181   [::ffff:62.**.***.***]:58646 users:(("clickhouse-keep",pid=806,fd=37))
      

      Успешное выполнение команды означает, что ваш ClickHouse Server на vm-test подключен к ClickHouse Keeper на vm-keeper.

• Координация репликации данных в кластерах ClickHouse^®.
• Автоматическая дедупликация вставок для реплицируемых таблиц MergeTree.
• Реализация очередей задач с использованием движка таблиц KeeperMap.
• Обеспечение доставки exactly-once в Kafka Connect Sink.
• Отслеживание обработанных файлов в S3Queue.
• Хранение метаданных для Replicated Database.
• Координация создания резервных копий кластера.
• Хранение пользовательских функций и настроек контроля доступа.
• Центральное хранилище метаданных для ClickHouse Cloud.

Служба технической поддержки Yandex Cloud отвечает на запросы 24 часа в сутки, 7 дней в неделю. Доступные виды запросов и срок их обработки зависят от тарифного плана. Подключить платную поддержку можно в консоли управления. Подробнее о порядке оказания технической поддержки.