Fichiers de configuration

• Si un nœud (c’est-à-dire un chemin menant à un élément) apparaît dans les deux fichiers et ne possède pas les attributs replace ou remove, il est inclus dans le fichier de configuration fusionné, et les éléments enfants des deux nœuds sont inclus puis fusionnés récursivement.
• Si l’un des deux nœuds contient l’attribut replace, il est inclus dans le fichier de configuration fusionné, mais seuls les éléments enfants du nœud portant l’attribut replace sont inclus.
• Si l’un des deux nœuds contient l’attribut remove, le nœud n’est pas inclus dans le fichier de configuration fusionné (s’il existe déjà, il est supprimé).

<clickhouse>
    <config_a>
        <setting_1>1</setting_1>
    </config_a>
    <config_b>
        <setting_2>2</setting_2>
    </config_b>
    <config_c>
        <setting_3>3</setting_3>
    </config_c>
</clickhouse>

<clickhouse>
    <config_a>
        <setting_4>4</setting_4>
    </config_a>
    <config_b replace="replace">
        <setting_5>5</setting_5>
    </config_b>
    <config_c remove="remove">
        <setting_6>6</setting_6>
    </config_c>
</clickhouse>

<clickhouse>
    <config_a>
        <setting_1>1</setting_1>
        <setting_4>4</setting_4>
    </config_a>
    <config_b>
        <setting_5>5</setting_5>
    </config_b>
</clickhouse>

<clickhouse>
    <profiles>
        <default>
            <max_query_size from_env="MAX_QUERY_SIZE"/>
        </default>
    </profiles>
</clickhouse>

<clickhouse>
    <profiles>
        <default>
            <max_query_size>150000</max_query_size>
        </default>
    </profiles>
</clickhouse>

<clickhouse>
    <postgresql_port from_zk="/zk_configs/postgresql_port"/>
</clickhouse>

# clickhouse-keeper-client
/ :) touch /zk_configs
/ :) create /zk_configs/postgresql_port "9005"
/ :) get /zk_configs/postgresql_port
9005

<clickhouse>
    <postgresql_port>9005</postgresql_port>
</clickhouse>

​

Interprétation des valeurs

• Une valeur directe substituée via from_env est considérée comme du texte littéral. Les caractères spéciaux XML tels que &, < et > sont échappés automatiquement ; une variable d’environnement peut donc contenir n’importe quelle valeur représentable en XML, par exemple a&b<c>d, sans casser la configuration (voir la note ci-dessous sur les caractères de contrôle interdits en XML). Une valeur directe n’est jamais interprétée comme du XML, même si elle ressemble à un fragment XML : <a>1</a> est substitué par le texte littéral <a>1</a>. Cela s’applique également lorsque l’attribut direct est placé sur un conteneur ordinaire tel que <profiles from_env="…"/> : une substitution de sous-arbre XML existante doit être migrée vers <profiles><include from_env="…"/></profiles>. Pour des raisons de rétrocompatibilité, <include from_env="…"/> se comporte différemment : il analyse la variable d’environnement comme un fragment XML et insère ses enfants dans l’élément parent.
• Le traitement d’une valeur substituée via from_zk dépend de ce qu’elle commence ou non par <. Une valeur commençant par < est toujours analysée comme un fragment XML : c’est ainsi qu’un sous-arbre est inséré dans n’importe quel élément, qu’il s’agisse d’un <include from_zk="…"/> structurel ou d’un conteneur ordinaire tel que <profiles from_zk="…"/> ; ce comportement est conservé pour des raisons de rétrocompatibilité, car les versions antérieures interprétaient toujours une valeur from_zk comme du XML. Une valeur ne commençant pas par < n’est analysée comme un sous-arbre YAML qu’avec la forme explicite <include from_zk="…" yaml="true"/> ; un YAML mal formé entraîne alors le rejet de la configuration. L’attribut yaml="true" active l’analyse YAML partout où la forme générique <include> est utilisée, y compris à l’intérieur d’un élément de certificat terminal ; ne l’utilisez donc pas pour un paramètre littéral ou un secret. Sans yaml="true", une valeur ne commençant pas par < est traitée comme du texte littéral, y compris lorsqu’elle est utilisée via la forme générique de remplacement de certificat terminal <password><include from_zk="/secret"/></password>. Les valeurs qui contiennent de la syntaxe YAML ou qui sont du YAML mal formé, comme abc # rotated ou [1, sont ainsi préservées. Avec cette forme, les octets exacts ne sont préservés que si l’<include> est intégré sans nœud de texte d’espacement autour ; pour les secrets et les paramètres de certificat terminal dont les octets exacts importent, privilégiez la forme directe <password from_zk="…"/>. Sur tout autre élément — qu’il s’agisse d’une substitution de certificat terminal telle que <some_setting from_zk="…"/> ou <password from_zk="…"/>, ou d’un conteneur ordinaire tel que <profiles from_zk="…"/> — une valeur ne commençant pas par < est également conservée comme texte littéral avec ses octets d’origine exacts (les caractères spéciaux XML sont échappés automatiquement, comme pour from_env) ; ainsi, une valeur telle que abc: def reste le texte littéral abc: def au lieu de devenir un sous-élément <abc>def</abc>. Pour insérer un sous-arbre dans un élément ordinaire (plutôt que dans un <include> structurel), fournissez-le sous forme de fragment XML (une valeur commençant par <).

<clickhouse>
    <profiles>
        <default>
            <max_query_size replace="1" from_env="MAX_QUERY_SIZE">150000</max_query_size>
        </default>
    </profiles>
</clickhouse>

<clickhouse>
    <profiles>
        <default>
            <max_query_size>150000</max_query_size>
        </default>
    </profiles>
</clickhouse>

• Substitution de valeurs : si un élément possède l’attribut incl, sa valeur sera remplacée par le contenu du fichier référencé. Le chemin vers le fichier contenant les substitutions est défini par l’élément include_from de la configuration du serveur ; aucun chemin n’est défini par défaut, les substitutions ne sont donc lues que lorsqu’il est spécifié. Les valeurs de substitution sont spécifiées dans les éléments /clickhouse/substitution_name de ce fichier. Si une substitution spécifiée dans incl n’existe pas, cela est consigné dans le journal. Pour empêcher ClickHouse de consigner les substitutions manquantes dans le journal, spécifiez l’attribut optional="true" (par exemple, pour les paramètres de macros).
• Substitution d’éléments : si vous souhaitez remplacer l’élément entier par une substitution, utilisez include comme nom d’élément. Le nom d’élément include peut être combiné avec l’attribut from_zk = "/path/to/node". Dans ce cas, la valeur de l’élément est remplacée par le contenu du nœud ZooKeeper situé à /path/to/node. Cela fonctionne également si vous stockez un sous-arbre XML entier dans un nœud ZooKeeper : il sera alors entièrement inséré dans l’élément source.

<clickhouse>
    <!-- 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>
</clickhouse>

<clickhouse>

    <encryption_codecs>
        <aes_128_gcm_siv>
            <key_hex>00112233445566778899aabbccddeeff</key_hex>
        </aes_128_gcm_siv>
    </encryption_codecs>

    <interserver_http_credentials>
        <user>admin</user>
        <password encrypted_by="AES_128_GCM_SIV">961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85</password>
    </interserver_http_credentials>

</clickhouse>

<clickhouse>

    <encryption_codecs>
        <aes_128_gcm_siv>
            <key_hex from_env="CLICKHOUSE_KEY_HEX"/>
        </aes_128_gcm_siv>
    </encryption_codecs>

    <interserver_http_credentials>
        <user>admin</user>
        <password encrypted_by="AES_128_GCM_SIV">961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85</password>
    </interserver_http_credentials>

</clickhouse>

<clickhouse>

    <encryption_codecs>
        <aes_128_gcm_siv>
            <key_hex from_zk="/clickhouse/aes128_key_hex"/>
        </aes_128_gcm_siv>
    </encryption_codecs>

    <interserver_http_credentials>
        <user>admin</user>
        <password encrypted_by="AES_128_GCM_SIV">961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85</password>
    </interserver_http_credentials>

</clickhouse>

<clickhouse>

    <encryption_codecs>
        <aes_128_gcm_siv>
            <key_hex from_zk="/clickhouse/aes128_key_hex"/>
        </aes_128_gcm_siv>
    </encryption_codecs>

</clickhouse>

<clickhouse>

    <users>
        <test_user>
            <password encrypted_by="AES_128_GCM_SIV">96280000000D000000000030D4632962295D46C6FA4ABF007CCEC9C1D0E19DA5AF719C1D9A46C446</password>
            <profile>default</profile>
        </test_user>
    </users>

</clickhouse>

./encrypt_decrypt /etc/clickhouse-server/config.xml -e AES_128_GCM_SIV abcd

961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85

<clickhouse>

    <interserver_http_credentials hide_in_preprocessed="true">
        <user>admin</user>
        <password>secret</password>
    </interserver_http_credentials>

</clickhouse>

$ cat /etc/clickhouse-server/users.d/alice.xml

<clickhouse>
    <users>
      <alice>
          <profile>analytics</profile>
            <networks>
                  <ip>::/0</ip>
            </networks>
          <password_sha256_hex>...</password_sha256_hex>
          <quota>analytics</quota>
      </alice>
    </users>
</clickhouse>

​

Exemples YAML

key: value

<key>value</key>

map_key:
  key1: val1
  key2: val2
  key3: val3

<map_key>
    <key1>val1</key1>
    <key2>val2</key2>
    <key3>val3</key3>
</map_key>

seq_key:
  - val1
  - val2
  - key1: val3
  - map:
      key2: val4
      key3: val5

<seq_key>val1</seq_key>
<seq_key>val2</seq_key>
<seq_key>
    <key1>val3</key1>
</seq_key>
<seq_key>
    <map>
        <key2>val4</key2>
        <key3>val5</key3>
    </map>
</seq_key>

map:
  "@attr1": value1
  "@attr2": value2
  key: 123

<map attr1="value1" attr2="value2">
    <key>123</key>
</map>

seq:
  - "@attr1": value1
  - "@attr2": value2
  - 123
  - abc

<seq attr1="value1" attr2="value2">123</seq>
<seq attr1="value1" attr2="value2">abc</seq>

map_key:
  "@attr1": value1
  "#text": value2

<map_key attr1="value1">value2</map_key>