ClickHouse Keeper (clickhouse-keeper)

Not supported in ClickHouse Cloud

примечание

This page is not applicable to ClickHouse Cloud. The procedure documented here is automated in ClickHouse Cloud services.

ClickHouse Keeper предоставляет систему координации для репликации данных и выполнения распределенных DDL запросов. ClickHouse Keeper совместим с ZooKeeper.

Подробности реализации

ZooKeeper является одной из первых известных систем координации с открытым исходным кодом. Она реализована на Java и имеет довольно простую и мощную модель данных. Алгоритм координации ZooKeeper, ZooKeeper Atomic Broadcast (ZAB), не предоставляет гарантии линейной согласованности для чтений, потому что каждый узел ZooKeeper обслуживает чтения локально. В отличие от ZooKeeper, ClickHouse Keeper написан на C++ и использует алгоритм RAFT реализация. Этот алгоритм позволяет обеспечить линейную согласованность для чтений и записей и имеет несколько открытых реализаций на разных языках.

По умолчанию ClickHouse Keeper предоставляет те же гарантии, что и ZooKeeper: линейные записи и нелинейные чтения. У него есть совместимый клиент-серверный протокол, поэтому любой стандартный клиент ZooKeeper может использоваться для взаимодействия с ClickHouse Keeper. Снимки и журналы имеют несовместимый формат с ZooKeeper, но инструмент clickhouse-keeper-converter позволяет выполнить конвертацию данных ZooKeeper в снимки ClickHouse Keeper. Протокол межсерверного взаимодействия в ClickHouse Keeper также несовместим с ZooKeeper, поэтому смешанный кластер ZooKeeper / ClickHouse Keeper невозможен.

ClickHouse Keeper поддерживает списки контроля доступа (ACL) так же, как это делает ZooKeeper. ClickHouse Keeper поддерживает тот же набор разрешений и имеет идентичные встроенные схемы: world, auth и digest. Схема аутентификации digest использует пару имя_пользователя:пароль, пароль кодируется в Base64.

примечание

Внешние интеграции не поддерживаются.

Конфигурация

ClickHouse Keeper может использоваться как самостоятельная замена ZooKeeper или как внутренняя часть сервера ClickHouse. В обоих случаях конфигурация практически одинакова и представляется в виде файла .xml.

Настройки конфигурации Keeper

Основной тег конфигурации ClickHouse Keeper — <keeper_server>, и он имеет следующие параметры:

Параметр	Описание	Значение по умолчанию
tcp_port	Порт для подключения клиента.	2181
tcp_port_secure	Защищенный порт для SSL-соединения между клиентом и keeper-server.	-
server_id	Уникальный идентификатор сервера, каждый участник кластера ClickHouse Keeper должен иметь уникальный номер (1, 2, 3 и так далее).	-
log_storage_path	Путь к журналам координации, так же как и ZooKeeper, лучше хранить журналы на не загруженных узлах.	-
snapshot_storage_path	Путь к снимкам координации.	-
enable_reconfiguration	Включить динамическую реорганизацию кластера через reconfig.	False
max_memory_usage_soft_limit	Мягкий лимит в байтах на максимальное использование памяти keeper.	max_memory_usage_soft_limit_ratio * physical_memory_amount
max_memory_usage_soft_limit_ratio	Если max_memory_usage_soft_limit не задан или равен нулю, используется это значение для определения мягкого лимита по умолчанию.	0.9
cgroups_memory_observer_wait_time	Если max_memory_usage_soft_limit не установлен или установлен в 0, мы используем этот интервал для мониторинга объема физической памяти. После изменения объема памяти мы пересчитаем мягкий лимит памяти Keeper по max_memory_usage_soft_limit_ratio.	15
http_control	Конфигурация HTTP control интерфейса.	-
digest_enabled	Включить проверку согласованности данных в реальном времени	True
create_snapshot_on_exit	Создать снимок во время завершения работы	-
hostname_checks_enabled	Включить проверку корректности имени хоста для конфигурации кластера (например, если localhost используется с удаленными конечными точками)	True
four_letter_word_white_list	Белый список команд 4lw.	conf, cons, crst, envi, ruok, srst, srvr, stat, wchs, dirs, mntr, isro, rcvr, apiv, csnp, lgif, rqld, ydld

Другие общие параметры унаследованы от конфигурации сервера ClickHouse (listen_host, logger и так далее).

Внутренние настройки координации

Внутренние настройки координации расположены в секции <keeper_server>.<coordination_settings> и имеют следующие параметры:

Параметр	Описание	Значение по умолчанию
operation_timeout_ms	Таймаут для одной операции клиента (мс)	10000
min_session_timeout_ms	Минимальный таймаут для сессии клиента (мс)	10000
session_timeout_ms	Максимальный таймаут для сессии клиента (мс)	100000
dead_session_check_period_ms	Как часто ClickHouse Keeper проверяет мертвые сессии и удаляет их (мс)	500
heart_beat_interval_ms	Как часто лидер ClickHouse Keeper будет отправлять сигналы жизни последователям (мс)	500
election_timeout_lower_bound_ms	Если последователь не получает сигнал жизни от лидера в этом интервале, он может инициировать выборы лидера. Должен быть меньше либо равен election_timeout_upper_bound_ms. Идеально, чтобы они не были равны.	1000
election_timeout_upper_bound_ms	Если последователь не получает сигнал жизни от лидера в этом интервале, он должен инициировать выборы лидера.	2000
rotate_log_storage_interval	Сколько записей журнала хранить в одном файле.	100000
reserved_log_items	Сколько записей журнала координации хранить перед компой.	100000
snapshot_distance	Как часто ClickHouse Keeper будет создавать новые снимки (в количестве записей в журналах).	100000
snapshots_to_keep	Сколько снимков сохранить.	3
stale_log_gap	Порог, когда лидер считает последователь устаревшим и отправляет ему снимок вместо журналов.	10000
fresh_log_gap	Когда узел становится свежим.	200
max_requests_batch_size	Максимальный размер партии в количестве запросов, прежде чем они будут отправлены в RAFT.	100
force_sync	Вызывать fsync при каждой записи в журнал координации.	true
quorum_reads	Выполнять запросы на чтение как записи через весь консенсус RAFT с аналогичной скоростью.	false
raft_logs_level	Уровень текстового логирования о координации (trace, debug и так далее).	system default
auto_forwarding	Разрешить перенаправление запросов на запись от последователей к лидеру.	true
shutdown_timeout	Ждать завершения внутренних подключений и остановки (мс).	5000
startup_timeout	Если сервер не подключается к другим участникам кворума в указанный таймаут, он завершится (мс).	30000
async_replication	Включить асинхронную репликацию. Все гарантии записи и чтения сохраняются, при этом достигается лучшая производительность. Настройка отключена по умолчанию, чтобы не нарушать обратную совместимость	false
latest_logs_cache_size_threshold	Максимальный общий размер кэша последних записей журнала в памяти	1GiB
commit_logs_cache_size_threshold	Максимальный общий размер кэша записей журнала, необходимых для подтверждения	500MiB
disk_move_retries_wait_ms	Как долго ждать между попытками после сбоя, который произошел во время перемещения файла между дисками	1000
disk_move_retries_during_init	Количество попыток после сбоя, который произошел во время перемещения файла между дисками во время инициализации	100
experimental_use_rocksdb	Использовать rocksdb как бекенд хранилища	0

Конфигурация кворума находится в секции <keeper_server>.<raft_configuration> и содержит описание серверов.

Единственным параметром для всего кворума является secure, который включает зашифрованное соединение для связи между участниками кворума. Параметр может быть установлен в true, если SSL-соединение требуется для внутренней связи между узлами, или оставлен неопределенным в противном случае.

Основные параметры для каждого <server>:

• id — Идентификатор сервера в кворуме.
• hostname — Имя хоста, где размещён этот сервер.
• port — Порт, на котором этот сервер слушает подключения.
• can_become_leader — Установите в false, чтобы настроить сервер как learner. Если не указано, значение будет true.

примечание

В случае изменения топологии вашего кластера ClickHouse Keeper (например, замена сервера), пожалуйста, убедитесь, что сопоставление server_id с hostname остается последовательным и избегайте перемешивания или повторного использования существующего server_id для разных серверов (например, это может произойти, если вы полагаетесь на скрипты автоматизации для развертывания ClickHouse Keeper)

Если хост экземпляра Keeper может измениться, рекомендуется определять и использовать имя хоста вместо сырых IP-адресов. Изменение имени хоста равно удалению и повторному добавлению сервера, что в некоторых случаях может быть невозможно (например, недостаточно экземпляров Keeper для кворума).

примечание

async_replication отключен по умолчанию, чтобы избежать нарушения обратной совместимости. Если у вас есть все экземпляры Keeper в кластере, работающем на версии, поддерживающей async_replication (v23.9+), мы рекомендуем включить его, так как это может улучшить производительность без каких-либо недостатков.

Примеры конфигурации для кворума с тремя узлами можно найти в интеграционных тестах с префиксом test_keeper_. Пример конфигурации для сервера #1:

Как запустить

ClickHouse Keeper включен в пакет сервера ClickHouse, просто добавьте конфигурацию <keeper_server> в ваш файл /etc/your_path_to_config/clickhouse-server/config.xml и запустите сервер ClickHouse, как всегда. Если вы хотите запустить автономный ClickHouse Keeper, вы можете запустить его аналогичным образом:

Если у вас нет символической ссылки (clickhouse-keeper), вы можете создать её или указать keeper в качестве аргумента для clickhouse:

Четырехбуквенные Команды

ClickHouse Keeper также предоставляет команды 4lw, которые почти такие же, как и в Zookeeper. Каждая команда состоит из четырех букв, таких как mntr, stat и т. д. Есть несколько более интересных команд: stat предоставляет общую информацию о сервере и подключенных клиентах, в то время как srvr и cons дают расширенные сведения о сервере и соединениях соответственно.

Команды 4lw имеют конфигурацию белого списка four_letter_word_white_list, значение по умолчанию которой conf,cons,crst,envi,ruok,srst,srvr,stat,wchs,dirs,mntr,isro,rcvr,apiv,csnp,lgif,rqld,ydld.

Вы можете отправить команды ClickHouse Keeper через telnet или nc, на клиентский порт.

Ниже представлены подробные команды 4lw:

• ruok: Проверяет, работает ли сервер в состоянии без ошибок. Сервер ответит imok, если он работает. В противном случае он совсем не ответит. Ответ imok не обязательно означает, что сервер вошел в кворум, просто процесс сервера активен и привязан к указанному клиентскому порту. Используйте "stat" для получения подробной информации о состоянии с точки зрения кворума и информации о подключении клиентов.

• mntr: Выводит список переменных, которые можно использовать для мониторинга состояния кластера.

• srvr: Перечисляет полные сведения о сервере.

• stat: Перечисляет краткие сведения о сервере и подключенных клиентах.

• srst: Сбрасывает статистику сервера. Эта команда повлияет на результат srvr, mntr и stat.

• conf: Печатает детали о конфигурации обслуживания.

• cons: Перечисляет полные детали соединений/сессий для всех клиентов, подключенных к этому серверу. Включает информацию о количестве полученных/отправленных пакетов, идентификаторе сессии, времена операций, последней выполненной операции и т. д.

• crst: Сбрасывает статистику соединений/сессий для всех соединений.

• envi: Печатает детали о среде выполнения

• dirs: Показывает общий размер файлов снимков и журналов в байтах.

• isro: Проверяет, работает ли сервер в режиме только для чтения. Сервер ответит ro, если находится в режиме только для чтения, или rw, если не находится в режиме только для чтения.

• wchs: Перечисляет краткую информацию о наблюдениях для сервера.

• wchc: Перечисляет подробную информацию о наблюдениях для сервера, по сессиям. Это выводит список сессий (соединений) с связанными наблюдениями (путями). Обратите внимание, что в зависимости от количества наблюдений эта операция может быть затратной (влиять на производительность сервера), используйте её осторожно.

• wchp: Перечисляет подробную информацию о наблюдениях для сервера, по путям. Это выводит список путей (znodes) с связанными сессиями. Обратите внимание, что в зависимости от количества наблюдений эта операция может быть затратной (т.е. влиять на производительность сервера), используйте её осторожно.

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

• csnp: Запланировать задачу создания снимка. Возвращает последний подтвержденный индекс журнала запланированного снимка, если успешно, или Не удалось запланировать задачу создания снимка. если завершилось неудачей. Обратите внимание, что команда lgif может помочь вам определить, завершен ли снимок.

• lgif: Информация о журнале Kipper. first_log_idx: мой первый индекс журнала в хранилище журналов; first_log_term: мой первый термин журнала; last_log_idx: мой последний индекс журнала в хранилище; last_log_term: мой последний термин журнала; last_committed_log_idx: мой последний подтвержденный индекс журнала в состоянии машины; leader_committed_log_idx: индекс журнала, подтвержденный лидером с моей точки зрения; target_committed_log_idx: целевой индекс журнала, который должен быть подтвержден; last_snapshot_idx: наибольший подтвержденный индекс журнала в последнем снимке.

• rqld: Запрос на становление новым лидером. Возвращает Отправлен запрос на лидерство лидеру. если запрос отправлен, или Не удалось отправить запрос на лидерство лидеру. если запрос не был отправлен. Обратите внимание, что если узел уже является лидером, результат будет тем же, так как запрос отправляется.

• ftfl: Перечисляет все флаги функций и то, включены ли они для инстанса Keeper.

• ydld: Запрос на отказ от лидерства и становление последователем. Если сервер, получающий запрос, является лидером, он сначала приостановит операции записи, подождет, пока преемник (текущий лидер не может быть преемником) завершит подгружение последнего журнала, а затем уйдет в отставку. Преемник будет выбран автоматически. Возвращает Отправлен запрос на отказ от лидерства лидеру. если запрос отправлен или Не удалось отправить запрос на отказ от лидерства лидеру. если запрос не был отправлен. Обратите внимание, что если узел уже является последователем, результат будет тем же, так как запрос отправляется.

• pfev: Возвращает значения для всех собранных событий. Для каждого события он возвращает имя события, значение события и описание события.

HTTP Управление

ClickHouse Keeper предоставляет HTTP интерфейс для проверки готовности реплики к получению трафика. Он может использоваться в облачных средах, таких как Kubernetes.

Пример конфигурации, которая включает в себя конечную точку /ready:

Флаги функций

Keeper полностью совместим с ZooKeeper и его клиентами, но также вводит некоторые уникальные функции и типы запросов, которые могут использоваться клиентом ClickHouse. Поскольку эти функции могут ввести изменения, несовместимые с предыдущими версиями, большинство из них отключены по умолчанию и могут быть включены с помощью конфигурации keeper_server.feature_flags. Все функции могут быть отключены явно. Если вы хотите включить новую функцию для вашего кластера Keeper, мы рекомендуем сначала обновить все инстансы Keeper в кластере до версии, которая поддерживает эту функцию, а затем включить саму функцию.

Пример конфигурации флагов функций, которая отключает multi_read и включает check_not_exists:

Доступные функции:

multi_read - поддержка многопроцессного чтения. По умолчанию: 1 filtered_list - поддержка запроса списка, который фильтрует результаты по типу узла (эфемерный или постоянный). По умолчанию: 1 check_not_exists - поддержка запроса CheckNotExists, который утверждает, что узел не существует. По умолчанию: 0 create_if_not_exists - поддержка запросов CreateIfNotExists, которые попытаются создать узел, если его не существует. Если он существует, изменения не применяются, и возвращается ZOK. По умолчанию: 0

Миграция с ZooKeeper

Бесшовная миграция с ZooKeeper на ClickHouse Keeper невозможна. Вам нужно остановить ваш кластер ZooKeeper, конвертировать данные и запустить ClickHouse Keeper. Инструмент clickhouse-keeper-converter позволяет конвертировать журналы и снимки ZooKeeper в снимок ClickHouse Keeper. Он работает только с ZooKeeper > 3.4. Шаги миграции:

1. Остановите все узлы ZooKeeper.

2. Необязательно, но рекомендуется: найдите узел-лидера ZooKeeper, запустите его и остановите снова. Это заставит ZooKeeper создать согласованный снимок.

3. Запустите clickhouse-keeper-converter на лидере, например:

4. Скопируйте снимок на узлы сервера ClickHouse с настроенным keeper или запустите ClickHouse Keeper вместо ZooKeeper. Снимок должен храниться на всех узлах, в противном случае пустые узлы могут быть быстрее, и один из них может стать лидером.

примечание

Инструмент keeper-converter недоступен из отдельного двоичного файла Keeper. Если у вас установлен ClickHouse, вы можете использовать двоичный файл напрямую:

В противном случае вы можете скачать двоичный файл и запустить инструмент, как описано выше, без установки ClickHouse.

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

Поскольку ClickHouse Keeper использует Raft, он может выдерживать определенное количество сбоев узлов в зависимости от размера кластера.
Например, для кластера из 3 узлов он будет продолжать работать правильно, если только 1 узел выйдет из строя.

Конфигурация кластера может настраиваться динамически, но есть некоторые ограничения. Переконфигурация также зависит от Raft, поэтому для добавления/удаления узла из кластера необходимо иметь кворум. Если вы потеряете слишком много узлов в вашем кластере одновременно без возможности их повторного запуска, Raft прекратит работу и не позволит вам переконфигурировать ваш кластер обычным способом.

Тем не менее, ClickHouse Keeper имеет режим восстановления, который позволяет вам принудительно переконфигурировать ваш кластер всего с одним узлом. Это должно быть сделано только в качестве последнего средства, если вы не можете снова запустить ваши узлы или запустить новый экземпляр на том же конечном пункте.

Важно, о чем следует помнить перед продолжением:

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

После того, как вы убедитесь, что вышеуказанные вещи верны, вам нужно сделать следующее:

1. Выберите один узел Keeper, который станет вашим новым лидером. Имейте в виду, что данные этого узла будут использоваться для всего кластера, поэтому мы рекомендуем использовать узел с наиболее актуальным состоянием.
2. Прежде чем делать что-либо еще, сделайте резервную копию папок log_storage_path и snapshot_storage_path выбранного узла.
3. Переконфигурируйте кластер на всех узлах, которые вы хотите использовать.
4. Отправьте команду из четырех букв rcvr на узел, который вы выбрали, что переведет узел в режим восстановления ИЛИ остановите экземпляр Keeper на выбранном узле и запустите его снова с аргументом --force-recovery.
5. Один за другим запустите экземпляры Keeper на новых узлах, убедившись, что mntr возвращает follower для zk_server_state, прежде чем приступать к следующему узлу.
6. Находясь в режиме восстановления, узел-лидер будет возвращать сообщение об ошибке для команды mntr, пока не достигнет кворума с новыми узлами и будет отказывать в любых запросах от клиента и последователей.
7. После достижения кворума узел-следователь вернется к нормальному режиму работы, принимая все запросы, используя проверку Raft с mntr, который должен возвращать leader для zk_server_state.

Использование дисков с Keeper

Keeper поддерживает подмножество внешних дисков для хранения снимков, файлов журналов и файла состояния.

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

• s3_plain
• s3
• local

Ниже приведен пример определений дисков, содержащихся внутри конфигурации.

Чтобы использовать диск для журналов, конфигурация keeper_server.log_storage_disk должна быть установлена на имя диска. Чтобы использовать диск для снимков, конфигурация keeper_server.snapshot_storage_disk должна быть установлена на имя диска. Кроме того, для последних журналов или снимков могут использоваться разные диски с помощью keeper_server.latest_log_storage_disk и keeper_server.latest_snapshot_storage_disk соответственно. В этом случае Keeper автоматически переместит файлы на правильные диски, когда создаются новые журналы или снимки. Чтобы использовать диск для файла состояния, конфигурация keeper_server.state_storage_disk должна быть установлена на имя диска.

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

Keeper с установленной конфигурацией keeper_server.coordination_settings.force_sync на true (true по умолчанию) не может предоставить некоторые гарантии для всех типов дисков. В настоящее время только диски типа local поддерживают постоянную синхронизацию. Если используется force_sync, log_storage_disk должен быть локальным диском, если latest_log_storage_disk не используется. Если используется latest_log_storage_disk, он всегда должен быть локальным диском. Если force_sync отключен, диски всех типов могут использоваться в любой конфигурации.

Возможная конфигурация хранения для экземпляра Keeper может выглядеть следующим образом:

Этот экземпляр будет хранить все, кроме последних журналов, на диске log_s3_plain, тогда как последний журнал будет находиться на диске log_local. Такая же логика применяется для снимков, все, кроме последних снимков, будут храниться на snapshot_s3_plain, тогда как последний снимок будет находиться на диске snapshot_local.

Изменение конфигурации диска

к сведению

Перед применением новой конфигурации диска вручную создайте резервную копию всех журналов и снимков Keeper.

Если определена многоуровневая конфигурация диска (используются отдельные диски для последних файлов), Keeper попытается автоматически переместить файлы на правильные диски при запуске. Тот же принцип применяется как и ранее; пока файл полностью не перемещен на новый диск, он не удаляется со старого диска, поэтому несколько перезапусков могут быть безопасно выполнены.

Если необходимо переместить файлы на совершенно новый диск (или переместить с 2-дисковой конфигурации на однодисковую конфигурацию), возможно использовать несколько определений keeper_server.old_snapshot_storage_disk и keeper_server.old_log_storage_disk.

Следующая конфигурация показывает, как мы можем перейти с предыдущей 2-дисковой конфигурации на совершенно новую однодисковую конфигурацию:

При запуске все файлы журналов будут перемещены с log_local и log_s3_plain на диск log_local2. Также все файлы снимков будут перемещены с snapshot_local и snapshot_s3_plain на диск snapshot_local2.

Конфигурация кеша журналов

Чтобы минимизировать количество данных, читаемых с диска, Keeper кеширует записи журнала в памяти. Если запросы большие, записи журнала займут слишком много памяти, поэтому размер кеша журналов ограничен. Ограничение контролируется этими двумя конфигурациями:

• latest_logs_cache_size_threshold - общий размер последних журналов, хранящихся в кеше
• commit_logs_cache_size_threshold - общий размер последующих журналов, которые необходимо записать затем

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

примечание

Вы можете использовать команду pfev, чтобы проверить количество журналов, прочитанных из каждого кеша и из файла. Вы также можете использовать метрики с конечной точки Prometheus, чтобы отслеживать текущий размер обоих кешей.

Prometheus

Keeper может предоставлять данные метрик для сбора с Prometheus.

Настройки:

• endpoint – HTTP конечная точка для сбора метрик сервером Prometheus. Начинается с ‘/’.
• port – Порт для endpoint.
• metrics – Флаг, который устанавливает, чтобы предоставить метрики из таблицы system.metrics.
• events – Флаг, который устанавливает, чтобы предоставить метрики из таблицы system.events.
• asynchronous_metrics – Флаг, который устанавливает, чтобы предоставить текущие значения метрик из таблицы system.asynchronous_metrics.

Пример

Проверьте (замените 127.0.0.1 на IP-адрес или имя хоста вашего сервера ClickHouse):

Также смотрите интеграцию ClickHouse Cloud с Prometheus.

Руководство пользователя ClickHouse Keeper

Это руководство предоставляет простые и минимальные настройки для конфигурации ClickHouse Keeper с примером того, как тестировать распределенные операции. Этот пример выполняется с использованием 3 узлов на Linux.

1. Настройка узлов с настройками Keeper

1. Установите 3 экземпляра ClickHouse на 3 хоста (chnode1, chnode2, chnode3). (Посмотрите Быстрый старт для подробностей об установке ClickHouse.)

2. На каждом узле добавьте следующую запись, чтобы разрешить внешнюю связь через сетевой интерфейс.

3. Добавьте следующую конфигурацию ClickHouse Keeper на все три сервера, обновив настройку <server_id> для каждого сервера; для chnode1 это будет 1, для chnode2 будет 2 и т. д.

   Вот основные настройки, использованные выше:

   Параметр	Описание	Пример
   tcp_port	порт, используемый клиентами Keeper	9181, эквивалент 2181 как в zookeeper
   server_id	уникальный идентификатор каждого сервера ClickHouse Keeper, использующийся в конфигурации Raft	1
   coordination_settings	раздел для параметров, таких как тайм-ауты	таймауты: 10000, уровень журнала: trace
   server	определение сервера, участвующего в кластере	список определения каждого сервера
   raft_configuration	настройки для каждого сервера в кластере Keeper	сервер и настройки для каждого
   id	числовой идентификатор сервера для служб Keeper	1
   hostname	имя хоста, IP или FQDN каждого сервера в кластере Keeper	chnode1.domain.com
   port	порт, на котором осуществляется связь в рамках Keeper	9234

4. Включите компонент Zookeeper. Он будет использовать движок ClickHouse Keeper:

   Вот основные настройки, использованные выше:

   Параметр	Описание	Пример
   node	список узлов для соединений ClickHouse Keeper	запись настройки для каждого сервера
   host	имя хоста, IP или FQDN каждого узла ClickHouse keeper	chnode1.domain.com
   port	порт клиента ClickHouse Keeper	9181

5. Перезапустите ClickHouse и проверьте, что каждый экземпляр Keeper работает. Выполните следующую команду на каждом сервере. Команда ruok возвращает imok, если Keeper работает и здоров:

6. База данных system имеет таблицу с именем zookeeper, которая содержит детали ваших инстансов ClickHouse Keeper. Давайте посмотрим таблицу:

   Таблица выглядит следующим образом:

2. Настройка кластера в ClickHouse

1. Давайте настроим простой кластер с 2 шардми и только одной репликой на 2 узлах. Третий узел будет использоваться для достижения кворума для требований в ClickHouse Keeper. Обновите конфигурацию на chnode1 и chnode2. Следующий кластер определяет 1 шард на каждом узле, что в итоге дает 2 шарда без репликации. В этом примере некоторые данные будут находиться на одном узле, а некоторые - на другом узле:

   Параметр	Описание	Пример
   shard	список реплик в определения кластера	список реплик для каждого шарда
   replica	список настроек для каждой реплики	записи настроек для каждой реплики
   host	имя хоста, IP или FQDN сервера, который будет размещать реплику шардов	chnode1.domain.com
   port	порт, используемый для связи с использованием протокола tcp	9000
   user	имя пользователя, которое будет использоваться для аутентификации к экземплярам кластера	default
   password	пароль для пользователя, определенный для разрешения соединений с экземплярами кластера	ClickHouse123!

2. Перезапустите ClickHouse и убедитесь, что кластер был создан:

   Вы должны увидеть ваш кластер:

3. Создание и тестирование распределенной таблицы

1. Создайте новую базу данных в новом кластере, используя клиент ClickHouse на chnode1. Клаузула ON CLUSTER автоматически создаст базу данных на обоих узлах.

2. Создайте новую таблицу в базе данных db1. Вновь ON CLUSTER создаст таблицу на обоих узлах.

3. На узле chnode1 добавьте пару строк:

4. Добавьте пару строк на узле chnode2:

5. Обратите внимание, что выполнение оператора SELECT на каждом узле показывает только данные на этом узле. Например, на chnode1:

   На chnode2:

7. Вы можете создать Distributed таблицу, чтобы представить данные на двух шардах. Таблицы с движком Distributed не хранят никаких данных сами по себе, но позволяют распределенную обработку запросов на нескольких серверах. Чтения охватывают все шарды, а записи могут быть распределены по шардaм. Выполните следующий запрос на chnode1:

8. Обратите внимание, что запрос к dist_table возвращает все четыре строки данных с двух шардов:

Резюме

Этот гид продемонстрировал, как настроить кластер, используя ClickHouse Keeper. С ClickHouse Keeper вы можете настраивать кластеры и определять распределенные таблицы, которые могут быть реплицированы по шардом.

Настройка ClickHouse Keeper с уникальными путями

Not supported in ClickHouse Cloud

примечание

This page is not applicable to ClickHouse Cloud. The procedure documented here is automated in ClickHouse Cloud services.

Описание

В этой статье описывается, как использовать встроенное свойство макроса {uuid} для создания уникальных записей в ClickHouse Keeper или ZooKeeper. Уникальные пути помогают при частом создании и удалении таблиц, потому что это предотвращает необходимость ждать несколько минут для завершения очистки неиспользуемых путей хранителем, так как каждый раз, когда создается путь, используется новый uuid в этом пути; пути никогда не повторяются.

Пример окружения

Трехузловой кластер, который будет настроен для работы с ClickHouse Keeper на всех трех узлах и ClickHouse на двух из узлов. Это обеспечивает ClickHouse Keeper тремя узлами (включая узел, принимающий решение), и один ClickHouse шард, состоящий из двух реплик.

узел	описание
chnode1.marsnet.local	узел данных - кластер cluster_1S_2R
chnode2.marsnet.local	узел данных - кластер cluster_1S_2R
chnode3.marsnet.local	узел, принимающий решение ClickHouse Keeper

Пример конфигурации для кластера:

Процедуры для настройки таблиц с использованием {uuid}

1. Настройка макросов на каждом сервере пример для сервера 1:

примечание

Обратите внимание, что мы определяем макросы для shard и replica, но макрос {uuid} здесь не определен, он встроенный, и нет необходимости в его определении.

2. Создайте базу данных

3. Создайте таблицу в кластере с использованием макросов и {uuid}

4. Создайте распределенную таблицу

Тестирование

1. Вставьте данные в первый узел (например, chnode1)

2. Вставьте данные во второй узел (например, chnode2)

3. Просмотрите записи, используя распределенную таблицу

Альтернативы

Путь репликации по умолчанию можно задать заранее с помощью макросов и использования также {uuid}

1. Установите значение по умолчанию для таблиц на каждом узле

подсказка

Вы также можете определить макрос {database} на каждом узле, если узлы используются для определенных баз данных.

2. Создайте таблицу без явных параметров:

3. Убедитесь, что использованы настройки, указанные в конфигурации по умолчанию

Устранение неполадок

Пример команды для получения информации о таблице и UUID:

Пример команды для получения информации о таблице в ZooKeeper с UUID для вышеуказанной таблицы

примечание

База данных должна быть Atomic, если происходит обновление с предыдущей версии, база данных default вероятно типа Ordinary.

Для проверки:

Например,

Динамическая перенастройка ClickHouse Keeper

Not supported in ClickHouse Cloud

примечание

This page is not applicable to ClickHouse Cloud. The procedure documented here is automated in ClickHouse Cloud services.

Описание

ClickHouse Keeper частично поддерживает команду ZooKeeper reconfig для динамической перенастройки кластера, если keeper_server.enable_reconfiguration включен.

примечание

Если этот параметр отключен, вы можете перенастроить кластер, изменив раздел raft_configuration у реплики вручную. Убедитесь, что вы редактируете файлы на всех репликах, так как только лидер применит изменения. В качестве альтернативы вы можете отправить запрос reconfig через любой совместимый с ZooKeeper клиент.

Виртуальный узел /keeper/config содержит последнюю зафиксированную конфигурацию кластера в следующем формате:

• Каждая запись сервера отделена переводом строки.
• server_type - либо participant, либо learner (learner не участвует в выборах лидера).
• server_priority - неотрицательное целое число, указывающее какие узлы должны иметь приоритет при выборах лидера. Приоритет 0 означает, что сервер никогда не будет лидером.

Пример:

Вы можете использовать команду reconfig, чтобы добавить новые серверы, удалить существующие и изменить приоритеты существующих серверов, вот примеры (с использованием clickhouse-keeper-client):

И вот примеры для kazoo:

Серверы в joining должны соответствовать формату, описанному выше. Записи серверов должны разделяться запятыми. При добавлении новых серверов вы можете опустить server_priority (значение по умолчанию равно 1) и server_type (значение по умолчанию равно participant).

Если вы хотите изменить приоритет существующего сервера, добавьте его в joining с целевым приоритетом. Хост сервера, порт и тип должны совпадать с текущей конфигурацией сервера.

Серверы добавляются и удаляются в порядке их появления в joining и leaving. Все обновления из joining обрабатываются перед обновлениями из leaving.

Существует несколько подводных камней в реализации перенастройки Keeper:

• Поддерживается только инкрементальная перенастройка. Запросы с непустыми new_members отклоняются.

  Реализация ClickHouse Keeper полагается на API NuRaft для динамического изменения членства. NuRaft позволяет добавлять один сервер или удалять один сервер по одному. Это означает, что каждое изменение конфигурации (каждая часть joining, каждая часть leaving) должно решаться отдельно. Таким образом, массовая перенастройка недоступна, так как это будет вводить в заблуждение конечных пользователей.

  Изменение типа сервера (participant/learner) также невозможно, так как это не поддерживается NuRaft, и единственный способ - удалить и добавить сервер, что снова будет вводить в заблуждение.

• Вы не можете использовать возвращаемое значение znodestat.

• Поле from_version не используется. Все запросы с установленным from_version отклоняются. Это связано с тем, что /keeper/config - виртуальный узел, что означает, что он не хранится в постоянной памяти, а генерируется на лету с указанной конфигурации узла для каждого запроса. Это решение было принято для предотвращения дублирования данных, так как NuRaft уже хранит эту конфигурацию.

• В отличие от ZooKeeper, нет возможности ожидать перенастройку кластера, отправляя команду sync. Новая конфигурация будет в конечном итоге применена, но без временных гарантий.

• Команда reconfig может завершиться неудачей по различным причинам. Вы можете проверить состояние кластера и увидеть, было ли обновление применено.

Преобразование одноместного хранилища в кластер

Иногда необходимо расширить экспериментальный узел хранилища в кластер. Вот схема, как это сделать шаг за шагом для кластера из 3 узлов:

• ВАЖНО: новые узлы должны добавляться пакетами менее чем текущий кворум, в противном случае они выберут лидера среди себя. В этом примере по одному.
• Существующий узел хранилища должен иметь включенный параметр конфигурации keeper_server.enable_reconfiguration.
• Запустите второй узел с полной новой конфигурацией кластера хранилища.
• После его запуска добавьте его к узлу 1, используя reconfig.
• Теперь запустите третий узел и добавьте его, используя reconfig.
• Обновите конфигурацию clickhouse-server, добавив новый узел хранилища туда, и перезапустите его для применения изменений.
• Обновите конфигурацию рафта узла 1 и, при необходимости, перезапустите его.

Чтобы уверенно ощутить процесс, вот песочница репозиторий.

Неподдерживаемые функции

Хотя ClickHouse Keeper стремится полностью совместим с ZooKeeper, существует несколько функций, которые в настоящее время не реализованы (хотя разработка продолжается):

• create не поддерживает возврат объекта Stat
• create не поддерживает TTL
• addWatch не работает с наблюдениямиPERSISTENT
• removeWatch и removeAllWatches не поддерживаются
• setWatches не поддерживается
• Создание CONTAINER типа znodes не поддерживается
• SASL аутентификация не поддерживается