mirror of
https://github.com/ClickHouse/ClickHouse.git
synced 2024-09-24 02:30:51 +00:00
156 lines
11 KiB
Markdown
156 lines
11 KiB
Markdown
---
|
||
toc_priority: 50
|
||
toc_title: "Конфигурационные файлы"
|
||
---
|
||
|
||
|
||
# Конфигурационные файлы {#configuration_files}
|
||
|
||
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 файлы должны иметь одинаковый корневой элемент, обычно `<yandex>`. Для YAML элемент `yandex:` должен отсутствовать, так как парсер вставляет его автоматически.
|
||
|
||
## Переопределение {#override}
|
||
|
||
Некоторые настройки, определенные в основном конфигурационном файле, могут быть переопределены в других файлах:
|
||
|
||
- У элементов этих конфигурационных файлов могут быть указаны атрибуты `replace` или `remove`.
|
||
- Если ни один атрибут не указан, сервер объединит содержимое элементов рекурсивно, заменяя совпадающие значения дочерних элементов.
|
||
- Если указан атрибут `replace`, сервер заменит весь элемент на указанный.
|
||
- Если указан атрибут `remove`, сервер удалит элемент.
|
||
|
||
Также возможно указать атрибуты как переменные среды с помощью `from_env="VARIABLE_NAME"`:
|
||
|
||
```xml
|
||
<yandex>
|
||
<macros>
|
||
<replica from_env="REPLICA" />
|
||
<layer from_env="LAYER" />
|
||
<shard from_env="SHARD" />
|
||
</macros>
|
||
</yandex>
|
||
```
|
||
|
||
## Подстановки {#substitution}
|
||
|
||
В конфигурационном файле могут быть указаны «подстановки». Если у элемента присутствует атрибут `incl`, то в качестве значения будет использована соответствующая подстановка из файла. По умолчанию путь к файлу с подстановками - `/etc/metrika.xml`. Он может быть изменён в конфигурации сервера в элементе [include_from](server-configuration-parameters/settings.md#server_configuration_parameters-include_from). Значения подстановок указываются в элементах `/clickhouse/имя_подстановки` этого файла. Если подстановка, заданная в `incl`, отсутствует, то делается соответствующая запись в лог. Чтобы ClickHouse фиксировал в логе отсутствие подстановки, необходимо указать атрибут `optional="true"` (например, настройки для [macros](server-configuration-parameters/settings.md#macros)).
|
||
|
||
Если нужно заменить весь элемент подстановкой, можно использовать `include` как имя элемента.
|
||
|
||
Пример подстановки XML:
|
||
|
||
```xml
|
||
<yandex>
|
||
<!-- Appends XML subtree found at `/profiles-in-zookeeper` ZK path to `<profiles>` element. -->
|
||
<profiles from_zk="/profiles-in-zookeeper" />
|
||
|
||
<users>
|
||
<!-- Replaces `include` element with the subtree found at `/users-in-zookeeper` ZK path. -->
|
||
<include from_zk="/users-in-zookeeper" />
|
||
<include from_zk="/other-users-in-zookeeper" />
|
||
</users>
|
||
</yandex>
|
||
```
|
||
|
||
Подстановки могут также выполняться из 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`.
|
||
Например, можно иметь по отдельному конфигурационному файлу для каждого пользователя:
|
||
|
||
``` bash
|
||
$ cat /etc/clickhouse-server/users.d/alice.xml
|
||
```
|
||
|
||
``` xml
|
||
<yandex>
|
||
<users>
|
||
<alice>
|
||
<profile>analytics</profile>
|
||
<networks>
|
||
<ip>::/0</ip>
|
||
</networks>
|
||
<password_sha256_hex>...</password_sha256_hex>
|
||
<quota>analytics</quota>
|
||
</alice>
|
||
</users>
|
||
</yandex>
|
||
```
|
||
|
||
Для каждого конфигурационного файла, сервер при запуске генерирует также файлы `file-preprocessed.xml`. Эти файлы содержат все выполненные подстановки и переопределения, и предназначены для информационных целей. Если в конфигурационных файлах были использованы ZooKeeper-подстановки, но при старте сервера ZooKeeper недоступен, то сервер загрузит конфигурацию из preprocessed-файла.
|
||
|
||
Сервер следит за изменениями конфигурационных файлов, а также файлов и ZooKeeper-узлов, которые были использованы при выполнении подстановок и переопределений, и перезагружает настройки пользователей и кластеров на лету. То есть, можно изменять кластера, пользователей и их настройки без перезапуска сервера.
|
||
|
||
## Примеры записи конфигурации на YAML {#example}
|
||
|
||
Здесь можно рассмотреть пример реальной конфигурации записанной на YAML: [config.yaml.example](https://github.com/ClickHouse/ClickHouse/blob/master/programs/server/config.yaml.example).
|
||
|
||
Между стандартами XML и YAML имеются различия, поэтому в этом разделе будут перечислены некоторые подсказки для написания конфигурации на YMAL.
|
||
|
||
Для записи обычной пары ключ-значение следует использовать Scalar:
|
||
``` yaml
|
||
key: value
|
||
```
|
||
|
||
Для создания тега, содержащего подтеги следует использовать Map:
|
||
``` yaml
|
||
map_key:
|
||
key1: val1
|
||
key2: val2
|
||
key3: val3
|
||
```
|
||
|
||
Для создания списка значений или подтегов, расположенных по определенному ключу, следует использовать Sequence:
|
||
``` yaml
|
||
seq_key:
|
||
- val1
|
||
- val2
|
||
- key1: val3
|
||
- map:
|
||
key2: val4
|
||
key3: val5
|
||
```
|
||
|
||
В случае, усли необходимо объявить тег, аналогичный XML-атрибуту, необходимо задать скаляр, имеющий ключ с префиксом @ и заключенный в кавычки:
|
||
|
||
``` yaml
|
||
map:
|
||
"@attr1": value1
|
||
"@attr2": value2
|
||
key: 123
|
||
```
|
||
|
||
Из такой Map мы получим после конвертации:
|
||
|
||
``` xml
|
||
<map attr1="value1" attr2="value2">
|
||
<key>123</key>
|
||
</map>
|
||
```
|
||
|
||
Помимо Map, можно задавать атрибуты для Sequence:
|
||
|
||
``` yaml
|
||
seq:
|
||
- "@attr1": value1
|
||
- "@attr2": value2
|
||
- 123
|
||
- abc
|
||
```
|
||
|
||
Таким образом получая аналог следующей записи на XML:
|
||
|
||
``` xml
|
||
<seq attr1="value1" attr2="value2">123</seq>
|
||
<seq attr1="value1" attr2="value2">abc</seq>
|
||
```
|
||
|
||
## Детали реализации {#implementation-details}
|
||
|
||
При старте сервера для каждого конфигурационного файла создаются файлы предобработки `file-preprocessed.xml`. Они содержат все выполненные подстановки и переопределения (эти сведения записываются просто для информации). Если в конфигурационном файле настроены подстановки ZooKeeper, но при старте сервера ZooKeeper не доступен, то сервер загружает конфигурацию из соответствующего файла предобработки.
|
||
|
||
Сервер отслеживает как изменения в конфигурационных файлах, так и файлы и узы ZooKeeper, которые были использованы при выполнении подстановок и переопределений, и на ходу перезагружает настройки для пользователей и кластеров. Это означает, что можно изменять кластеры, пользователей и их настройки без перезапуска сервера.
|