Конфигурационные файлы

ClickHouse поддерживает многофайловое управление конфигурацией. Основной конфигурационный файл сервера — /etc/clickhouse-server/config.xml или /etc/clickhouse-server/config.yaml. Остальные файлы должны находиться в директории /etc/clickhouse-server/config.d. Обратите внимание, что конфигурационные файлы могут быть записаны в форматах XML или YAML, но смешение этих форматов в одном файле не поддерживается. Например, можно хранить основные конфигурационные файлы как config.xml и users.xml, а дополнительные файлы записать в директории config.d и users.d в формате .yaml.

Все XML файлы должны иметь одинаковый корневой элемент, обычно <clickhouse>. Для YAML элемент clickhouse: должен отсутствовать, так как парсер вставляет его автоматически.

Переопределение

Некоторые настройки, определенные в основном конфигурационном файле, могут быть переопределены в других файлах:

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

Также возможно указать атрибуты как переменные среды с помощью from_env="VARIABLE_NAME":

Подстановки

В конфигурационном файле могут быть указаны «подстановки». Если у элемента присутствует атрибут incl, то в качестве значения будет использована соответствующая подстановка из файла. По умолчанию путь к файлу с подстановками - /etc/metrika.xml. Он может быть изменён в конфигурации сервера в элементе include_from. Значения подстановок указываются в элементах /clickhouse/имя_подстановки этого файла. Если подстановка, заданная в incl, отсутствует, то делается соответствующая запись в лог. Чтобы ClickHouse фиксировал в логе отсутствие подстановки, необходимо указать атрибут optional="true" (например, настройки для macros).

Если нужно заменить весь элемент подстановкой, можно использовать include как имя элемента.

Пример подстановки XML:

Подстановки могут также выполняться из ZooKeeper. Для этого укажите у элемента атрибут from_zk = "/path/to/node". Значение элемента заменится на содержимое узла /path/to/node в ZooKeeper. В ZooKeeper-узел также можно положить целое XML-поддерево, оно будет целиком вставлено в исходный элемент.

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

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

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

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

Шифрование и Скрытие

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

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

Пример:

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

Пример:

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

Пример:

Примеры записи конфигурации на YAML

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

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

Для записи обычной пары ключ-значение следует использовать Scalar:

Для создания тега, содержащего подтеги следует использовать Map:

Для создания списка значений или подтегов, расположенных по определенному ключу, следует использовать Sequence:

В случае, усли необходимо объявить тег, аналогичный XML-атрибуту, необходимо задать скаляр, имеющий ключ с префиксом @ и заключенный в кавычки:

Из такой Map мы получим после конвертации:

Помимо Map, можно задавать атрибуты для Sequence:

Таким образом получая аналог следующей записи на XML:

Детали реализации

При старте сервера для каждого конфигурационного файла создаются файлы предобработки file-preprocessed.xml. Они содержат все выполненные подстановки и переопределения (эти сведения записываются просто для информации). Если в конфигурационном файле настроены подстановки ZooKeeper, но при старте сервера ZooKeeper не доступен, то сервер загружает конфигурацию из соответствующего файла предобработки.

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