ClickHouse Keeper (clickhouse-keeper)

Not supported in ClickHouse Cloud

примечание

Эта страница не применима к ClickHouse Cloud. Процедура, описанная здесь, автоматизирована в сервисах ClickHouse Cloud.

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_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 контроля интерфейса.	-
digest_enabled	Включить проверку консистентности данных в реальном времени	True
create_snapshot_on_exit	Создать снимок во время завершения работы	-
hostname_checks_enabled	Включить проверку корректности указанных хостнеймов для конфигурации кластера (например, если локальный хост используется с удалёнными конечными точками)	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: Запланировать задачу создания снимка. Возвращает последний зафиксированный индекс журнала запланированного снимка, если успешно, или Failed to schedule snapshot creation task. если не удалось. Обратите внимание, что команда lgif может помочь вам определить, завершен ли снимок.

• lgif: Информация о журнале Keeper. 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: Запрос на становление новым лидером. Возвращает Sent leadership request to leader. если запрос отправлен или Failed to send leadership request to leader. если запрос не был отправлен. Обратите внимание, что если узел уже является лидером, результат будет таким же, как если бы запрос был отправлен.

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

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

• 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 узлом. Это следует делать только в качестве крайней меры, если вы не можете снова запустить свои узлы или запустить новый экземпляр на том же конечном пункте.

Важно отметить несколько вещей перед тем, как продолжить:

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

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

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 должен быть диском local, если latest_log_storage_disk не используется.
Если используется latest_log_storage_disk, он всегда должен быть диском local.
Если force_sync отключен, диски всех типов могут использоваться в любой конфигурации.

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

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

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

к сведению

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

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

Если необходимо переместить файлы на совершенно новый диск (или перейти с двухдисковой конфигурации на однодисковую), можно использовать несколько определений 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):

Пожалуйста, также ознакомьтесь с интеграцией Prometheus в ClickHouse Cloud.

Руководство пользователя 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 не хранят собственные данные, но позволяют распределенную обработку запросов на нескольких серверах. Чтения охватывают все шары, и записи могут быть распределены между шарами. Запустите следующий запрос на chnode1:

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

Резюме

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

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

Not supported in ClickHouse Cloud

примечание

Эта страница не применима к ClickHouse Cloud. Процедура, описанная здесь, автоматизирована в сервисах ClickHouse Cloud.

Описание

В этой статье описывается, как использовать встроенный {uuid} макрос для создания уникальных записей в ClickHouse Keeper или ZooKeeper. Уникальные пути помогают при частом создании и удалении таблиц, так как это позволяет избежать ожидания нескольких минут, пока сборщик мусора Keeper удалит записи пути. Каждый раз, когда создается путь, используется новый 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, если вы обновляете с предыдущей версии, то база данных по умолчанию, вероятно, типа Ordinary.

Чтобы проверить:

Например,

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

Not supported in ClickHouse Cloud

примечание

Эта страница не применима к ClickHouse Cloud. Процедура, описанная здесь, автоматизирована в сервисах ClickHouse Cloud.

Описание

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 может не удаваться по разным причинам. Вы можете проверить состояние кластера и посмотреть, были ли применены обновления.

Преобразование однузлового keeper в кластер

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

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

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

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

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

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