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 поддерживает списки контроля доступа (ACLs) так же, как и ZooKeeper. ClickHouse Keeper поддерживает тот же набор прав и имеет идентичные встроенные схемы: world, auth и digest. Схема аутентификации digest использует пару username:password, пароль кодируется в 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 интерфейса.	-
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: Информация о журнале 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: Запрос на становление новым лидером. Вернуть Отправлен запрос на лидерство в случае отправки запроса или Не удалось отправить запрос на лидерство. в случае, если запрос не был отправлен. Обратите внимание, что если узел уже является лидером, результат будет таким же, как и при отправке запроса.

• 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
• remove_recursive - поддержка запроса RemoveRecursive, который удаляет узел вместе с его поддеревом. По умолчанию: 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, которая должна вернуть 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 не хранят собственных данных, но позволяют обрабатывать распределенные запросы на нескольких серверах. Чтения охватывают все шардера, а записи могут распределяться по шардерам. Выполните следующий запрос на 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. Уникальные пути помогают при частом создании и удалении таблиц, поскольку это позволяет избежать ожидания нескольких минут, пока сборщик мусора 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, если вы обновляете с предыдущей версии, база данных 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) должно быть решено отдельно. Таким образом, нет доступной массовой перенастройки, так как это будет вводить в заблуждение конечных пользователей.

  Изменение типа сервера (участник/ученик) также невозможно, так как это не поддерживается 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 не поддерживается
• Создание CONTAINER типа znodes не поддерживается
• SASL authentication не поддерживается