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

примечание

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