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

примечание

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