Файлы конфигурации

примечание

Обратите внимание, что профили настроек и файлы конфигурации на основе XML в настоящее время не поддерживаются для ClickHouse Cloud. Поэтому в ClickHouse Cloud вы не найдете файл config.xml. Вместо этого вы должны использовать SQL команды для управления настройками через профили настроек.

Для получения дополнительных деталей смотрите "Настройка настроек"

Сервер ClickHouse может быть настроен с помощью файлов конфигурации в формате XML или YAML. В большинстве типов установки сервер ClickHouse работает с /etc/clickhouse-server/config.xml в качестве файла конфигурации по умолчанию, но также возможно вручную указать местоположение файла конфигурации при запуске сервера, используя параметр командной строки --config-file или -C. Дополнительные файлы конфигурации могут быть помещены в директорию config.d/ относительно основного файла конфигурации, например в директорию /etc/clickhouse-server/config.d/. Файлы в этой директории и основной файл конфигурации объединяются на этапе предварительной обработки перед тем, как конфигурация применяется на сервере ClickHouse. Файлы конфигурации объединяются в алфавитном порядке. Чтобы упростить обновления и улучшить модульность, рекомендуется оставлять файл config.xml без изменений и помещать дополнительные настройки в config.d/. Конфигурация ClickHouse keeper хранится в /etc/clickhouse-keeper/keeper_config.xml. Таким образом, дополнительные файлы должны быть помещены в /etc/clickhouse-keeper/keeper_config.d/.

Возможно смешивать файлы конфигурации XML и YAML, например, у вас может быть основной файл конфигурации config.xml и дополнительные файлы конфигурации config.d/network.xml, config.d/timezone.yaml и config.d/keeper.yaml. Смешивание XML и YAML в одном файле конфигурации не поддерживается. Файлы конфигурации XML должны использовать <clickhouse>...</clickhouse> в качестве корневого тега. В файлах конфигурации YAML clickhouse: является опциональным, если отсутствует, парсер автоматически вставляет его.

Объединение конфигурации

Два файла конфигурации (обычно основной файл конфигурации и другой файл конфигурации из config.d/) объединяются следующим образом:

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

Пример:

и

создает объединенный файл конфигурации:

Замена с помощью переменных окружения и узлов ZooKeeper

Чтобы указать, что значение элемента должно быть заменено значением переменной окружения, вы можете использовать атрибут from_env.

Пример с $MAX_QUERY_SIZE = 150000:

что равно

То же самое возможно с использованием from_zk (узел ZooKeeper):

что равно

Значения по умолчанию

Элемент с атрибутом from_env или from_zk может дополнительно иметь атрибут replace="1" (последний должен появляться перед from_env/from_zk). В этом случае элемент может определить значение по умолчанию. Элемент принимает значение переменной окружения или узла ZooKeeper, если оно установлено, в противном случае используется значение по умолчанию.

Предыдущее пример, но предположим, что MAX_QUERY_SIZE не установлен:

Результат:

Замена содержимым файла

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

• Замена значений: Если элемент имеет атрибут incl, его значение будет заменено на содержимое указанного файла. По умолчанию путь к файлу с заменами — /etc/metrika.xml. Это можно изменить в элементе include_from в конфигурации сервера. Значения замен указываются в элементах /clickhouse/substitution_name в этом файле. Если замена, указанная в incl, не существует, это записывается в лог. Чтобы предотвратить запись отсутствующих замен в лог ClickHouse, укажите атрибут optional="true" (например, настройки для макросов).

• Замена элементов: Если вы хотите заменить весь элемент на замену, используйте include в качестве имени элемента. Имя элемента include может быть объединено с атрибутом from_zk = "/path/to/node". В этом случае значение элемента заменяется содержимым узла ZooKeeper по адресу /path/to/node. Это также работает, если вы храните целое поддерево XML в узле ZooKeeper — оно будет полностью вставлено в исходный элемент.

Пример:

Если вы хотите объединить заменяющее содержимое с существующей конфигурацией вместо того, чтобы присоединять, вы можете использовать атрибут merge="true", например: <include from_zk="/some_path" merge="true">. В этом случае существующая конфигурация будет объединена с содержимым из замены, и настройки существующей конфигурации будут заменены значениями из замены.

Шифрование и сокрытие конфигурации

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

В отличие от атрибутов from_zk, from_env и incl, или элемента include, никакая замена (т.е. расшифровка зашифрованного значения) не выполняется в предварительно обработанном файле. Расшифровка происходит только во время выполнения в процессе сервера.

Пример:

Атрибуты from_env и from_zk также могут быть применены к encryption_codecs:

Ключи шифрования и зашифрованные значения могут быть определены в любом конфигурационном файле.

Пример config.xml:

Пример users.xml:

Чтобы зашифровать значение, вы можете использовать (пример) программу encrypt_decrypt:

Пример:

Даже если элементы конфигурации зашифрованы, зашифрованные элементы все равно появляются в предварительно обработанном файле конфигурации. Если это является проблемой для вашего развертывания ClickHouse, мы рекомендуем два альтернативных варианта: либо установить права доступа к предварительно обработанному файлу на 600, либо использовать атрибут hide_in_preprocessed.

Пример:

Пользовательские настройки

Файл config.xml может указывать отдельную конфигурацию с пользовательскими настройками, профилями и квотами. Относительный путь к этой конфигурации устанавливается в элементе users_config. По умолчанию это users.xml. Если users_config опущен, пользовательские настройки, профили и квоты указываются напрямую в config.xml.

Конфигурация пользователей может быть разделена на отдельные файлы, аналогично config.xml и config.d/. Имя директории определяется как настройка users_config без постфикса .xml, соединенного с .d. По умолчанию используется директория users.d, так как users_config по умолчанию указывает на users.xml.

Обратите внимание, что файлы конфигурации сначала объединяются, учитывая настройки, и включает обрабатываются после этого.

Пример XML

Например, вы можете иметь отдельный файл конфигурации для каждого пользователя, как это:

Примеры YAML

Здесь вы можете увидеть файл конфигурации по умолчанию, записанный в YAML: config.yaml.example.

Существуют некоторые отличия между форматами YAML и XML в терминах конфигураций ClickHouse. Вот несколько советов по написанию конфигурации в формате YAML.

XML-тег с текстовым значением представлен парой ключ-значение YAML

Соответствующий XML:

Вложенный XML-узел представлен картой YAML:

Соответствующий XML:

Чтобы создать один и тот же XML-тег несколько раз, используйте последовательность YAML:

Соответствующий XML:

Чтобы указать атрибут XML, вы можете использовать ключ атрибута с префиксом @. Обратите внимание, что @ зарезервирован стандартом YAML, поэтому его необходимо заключить в двойные кавычки:

Соответствующий XML:

Также возможно использование атрибутов в последовательности YAML:

Соответствующий XML:

Указанный выше синтаксис не позволяет выразить текстовые узлы XML с атрибутами XML в формате YAML. Этот специальный случай можно достичь, используя ключ атрибута #text:

Соответствующий XML:

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

Для каждого файла конфигурации сервер также генерирует файлы file-preprocessed.xml при запуске. Эти файлы содержат все завершенные замены и переопределения, и они предназначены для информационного использования. Если в файлах конфигурации использовались замены ZooKeeper, но ZooKeeper недоступен при запуске сервера, сервер загружает конфигурацию из предварительно обработанного файла.

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