Archivos de configuración

Los perfiles de configuración y los archivos de configuración basados en XML no son compatibles con ClickHouse Cloud. Por lo tanto, en ClickHouse Cloud no encontrarás un archivo config.xml. En su lugar, debes usar comandos SQL para gestionar la configuración mediante perfiles de configuración.Para obtener más detalles, consulta “Configuring Settings”

ClickHouse server se puede configurar con archivos de configuración en sintaxis XML o YAML. En la mayoría de los tipos de instalación, ClickHouse server se ejecuta con /etc/clickhouse-server/config.xml como archivo de configuración predeterminado, pero también es posible especificar manualmente la ubicación del archivo de configuración al iniciar el servidor mediante la opción de línea de comandos --config-file o -C. Si no se indica ninguna de estas opciones, el servidor busca config.xml, config.yaml y config.yml, en este orden, en el directorio de trabajo actual, y usa el primero que encuentre. Si no existe ninguno, el servidor se inicia con la configuración integrada en el binary. Un archivo indicado con --config-file se usa tal cual: si no existe, el servidor notifica un error en lugar de buscar un archivo con otra extensión. clickhouse-keeper sigue las mismas reglas con keeper_config.xml, keeper_config.yaml y keeper_config.yml. Se pueden colocar archivos de configuración adicionales en el directorio config.d/, relativo al archivo de configuración principal; por ejemplo, en el directorio /etc/clickhouse-server/config.d/. Los archivos de este directorio y la configuración principal se combinan en una etapa de preprocesamiento antes de que la configuración se aplique en ClickHouse server. Los fragmentos de configuración se combinan en orden lexicográfico según sus rutas completas. Para los archivos del directorio estándar config.d/, esto equivale a ordenarlos por nombre de archivo. También se combina el directorio heredado conf.d/; dado que conf.d se ordena antes que config.d, todos sus fragmentos se procesan primero cuando existen ambos directorios. Para simplificar las actualizaciones y mejorar la modularidad, se recomienda mantener el archivo config.xml predeterminado sin modificar y colocar la personalización adicional en config.d/. La configuración de ClickHouse Keeper se encuentra en /etc/clickhouse-keeper/keeper_config.xml. Del mismo modo, los archivos de configuración adicionales de Keeper deben colocarse en /etc/clickhouse-keeper/keeper_config.d/. Es posible mezclar archivos de configuración XML y YAML; por ejemplo, podrías tener un archivo de configuración principal config.xml y archivos de configuración adicionales config.d/network.xml, config.d/timezone.yaml y config.d/keeper.yaml. No se admite mezclar XML y YAML dentro de un mismo archivo de configuración. Los archivos de configuración XML deben usar <clickhouse>...</clickhouse> como etiqueta de nivel superior. En los archivos de configuración YAML, clickhouse: es opcional; si no está presente, el analizador lo inserta automáticamente.

Combinación de archivos de configuración

Dos archivos de configuración (normalmente, el archivo de configuración principal y otro archivo de configuración de config.d/) se combinan de la siguiente manera:

Si un nodo (es decir, una ruta que conduce a un elemento) aparece en ambos archivos y no tiene los atributos replace o remove, se incluye en el archivo de configuración combinado, y los elementos secundarios de ambos nodos se incluyen y se combinan recursivamente.
Si uno de los dos nodos contiene el atributo replace, se incluye en el archivo de configuración combinado, pero solo se incluyen los elementos secundarios del nodo con el atributo replace.
Si uno de los dos nodos contiene el atributo remove, el nodo no se incluye en el archivo de configuración combinado (si ya existe, se elimina).

Por ejemplo, dados dos archivos de configuración:

config.xml

<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>

config.d/other_config.xml

<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>

El archivo de configuración resultante de la combinación será:

<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>

Sustitución por variables de entorno y nodos de ZooKeeper

Para indicar que el valor de un elemento debe sustituirse por el valor de una variable de entorno, puedes usar el atributo from_env. Por ejemplo, con la variable de entorno $MAX_QUERY_SIZE = 150000:

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

La configuración resultante será:

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

También es posible usar from_zk (nodo de ZooKeeper):

<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

Esto da como resultado la siguiente configuración:

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

Cómo se interpretan los valores

from_env y from_zk difieren en la forma en que interpretan el valor sustituido:

Un valor directo sustituido mediante from_env se trata como texto literal. Los caracteres especiales de XML, como &, < y >, se escapan automáticamente, por lo que una variable de entorno puede contener cualquier valor representable en XML, por ejemplo a&b<c>d, sin romper la configuración (consulte más abajo la nota sobre los caracteres de control no válidos en XML). Un valor directo nunca se interpreta como XML, aunque parezca un fragmento XML: <a>1</a> sustituye el texto literal <a>1</a>. Esto también se aplica cuando el atributo directo se coloca en un contenedor ordinario como <profiles from_env="…"/>: una sustitución existente de un subárbol XML debe migrarse a <profiles><include from_env="…"/></profiles>. Por compatibilidad con versiones anteriores, <include from_env="…"/> se comporta de otra manera: analiza la variable de entorno como un fragmento XML e inserta sus elementos hijo en el elemento padre.
La interpretación de un valor sustituido mediante from_zk depende de si comienza con <. Un valor que comienza con < siempre se analiza como un fragmento XML: así es como se inserta un subárbol en cualquier elemento, tanto en un <include from_zk="…"/> estructural como en un contenedor ordinario como <profiles from_zk="…"/>; este comportamiento se mantiene por compatibilidad con versiones anteriores, ya que las versiones previas siempre interpretaban un valor de from_zk como XML. Un valor que no comienza con < se analiza como un subárbol YAML solo con la forma explícita <include from_zk="…" yaml="true"/>; en ese caso, un YAML mal formado provoca el rechazo de la configuración. El atributo yaml="true" habilita el análisis de YAML dondequiera que se use la forma genérica <include>, incluso dentro de un elemento hoja, por lo que no debe usarse para un ajuste literal ni para un secreto. Sin yaml="true", un valor que no comienza con < es texto literal, incluso cuando se utiliza mediante la forma genérica de reemplazo de hoja <password><include from_zk="/secret"/></password>. Así se conservan los valores que contienen sintaxis YAML o que son YAML mal formado, como abc # rotated o [1. En esa forma, los bytes exactos solo se conservan cuando el <include> está en línea, sin nodos de texto de espacios en blanco a su alrededor; para secretos y ajustes hoja en los que importan los bytes exactos, es preferible la forma directa <password from_zk="…"/>. En cualquier otro elemento —ya sea una sustitución hoja como <some_setting from_zk="…"/> o <password from_zk="…"/>, o un contenedor ordinario como <profiles from_zk="…"/>—, un valor que no comienza con < también se conserva como texto literal con sus bytes originales exactos (los caracteres especiales de XML se escapan automáticamente, igual que con from_env), de modo que un valor como abc: def sigue siendo el texto literal abc: def en lugar de convertirse en un subelemento <abc>def</abc>. Para insertar un subárbol en un elemento ordinario (y no en un <include> estructural), proporciónelo como un fragmento XML (un valor que comience con <).

Los valores literales deben ser texto XML 1.0 válidoUna sustitución literal (from_env, o un valor hoja de from_zk que no comienza con <) conserva los bytes exactos del valor para cualquier carácter que XML 1.0 pueda representar como texto. Los caracteres de control no válidos en XML 1.0 —0x00–0x08, 0x0B, 0x0C y 0x0E–0x1F— no pueden transmitirse de ningún modo a través de una configuración XML (la especificación XML los prohíbe incluso como referencias numéricas de caracteres, como ), y un valor que contenga alguno de ellos se rechaza al procesar la sustitución. El tabulador (\t), el salto de línea (\n) y el retorno de carro (\r) son válidos y se conservan byte a byte en el recorrido de ida y vuelta.

Comportamiento tras la actualización para valores hoja codificados con entidadesLas versiones anteriores volvían a analizar como XML cada valor from_env directo, por lo que un &, < o > sin procesar se rechazaba por no estar bien formado y la única forma de incluirlo era codificarlo como entidad XML: una variable de entorno con el valor a&b se decodificaba como a&b, <a>1</a> se decodificaba como <a>1</a> y  se decodificaba como un retorno de carro. Ahora, un valor from_env directo se trata como texto literal, por lo que esos mismos valores de entorno se resuelven como los literales a&b, <a>1</a> y . Por tanto, solo los valores de texto plano conservan intacto su significado anterior: un valor de entorno que se codificaba con entidades para la antigua ruta XML debe establecerse ahora sin procesar (por ejemplo, establezca a&b, que la ruta antigua rechazaba pero que la nueva acepta como el texto literal a&b).Las versiones anteriores volvían a analizar como XML cada valor hoja from_zk, por lo que un &, < o > sin procesar se rechazaba por no estar bien formado y la única forma de incluirlo era codificarlo como entidad XML: un valor almacenado como a&b se decodificaba como a&b, <a>1</a> se decodificaba como <a>1</a> y  se decodificaba como un retorno de carro. Ahora, un valor hoja que no empieza por < se conserva byte a byte tal como es originalmente, por lo que esos mismos nodos se resuelven ahora como los literales a&b, <a>1</a> y . Por tanto, solo los escalares de texto plano conservan intacto su significado anterior: un valor hoja que se codificaba con entidades para la antigua ruta XML debe almacenarse ahora sin procesar (por ejemplo, almacene a&b, que la ruta antigua rechazaba pero que la nueva acepta como el texto literal a&b).El mismo cambio se aplica a un escalar simple sustituido mediante un <include from_zk="…"/> en línea dentro de un ajuste hoja o de un secreto, por ejemplo <password><include from_zk="/secret"/></password>: en este caso, el escalar también se conserva byte a byte tal como es originalmente, por lo que /secret = a&b (que antes se decodificaba como a&b) ahora se resuelve como el literal a&b y debe almacenarse sin procesar como a&b. No deje espacios en blanco alrededor en esta forma, ya que esos espacios pasan a formar parte del valor resultante del ajuste; utilice preferentemente la forma directa <password from_zk="…"/> cuando importe conservar los bytes exactos. (Un valor from_zk que empieza por <, o un subárbol YAML referenciado con <include from_zk="…" yaml="true"/>, no se ve afectado: solo los valores sin marcar que no empiezan por < se conservan de forma literal).

Valores predeterminados

Un elemento con los atributos from_env o from_zk también puede tener el atributo replace="1" (este último debe aparecer antes de from_env/from_zk). En este caso, el elemento puede definir un valor predeterminado. El elemento toma el valor de la variable de entorno o del nodo de ZooKeeper si está definido; de lo contrario, toma el valor predeterminado. Se repite el ejemplo anterior, pero suponiendo que MAX_QUERY_SIZE no está definido:

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

Dando lugar a la siguiente configuración:

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

Sustitución con contenido de archivos

También es posible reemplazar partes de la configuración por el contenido de archivos. Esto puede hacerse de dos maneras:

Sustitución de valores: Si un elemento tiene el atributo incl, su valor se reemplazará por el contenido del archivo al que hace referencia. La ruta al archivo con las sustituciones se establece mediante el elemento include_from de la configuración del servidor; no hay una ruta predeterminada, por lo que las sustituciones solo se leen cuando se especifica. Los valores de sustitución se especifican en elementos /clickhouse/substitution_name dentro de este archivo. Si una sustitución especificada en incl no existe, se registra en el log. Para evitar que ClickHouse registre sustituciones ausentes, especifique el atributo optional="true" (por ejemplo, para la configuración de macros).
Sustitución de elementos: Si desea reemplazar el elemento completo por una sustitución, use include como nombre del elemento. El nombre de elemento include puede combinarse con el atributo from_zk = "/path/to/node". En este caso, el valor del elemento se reemplaza por el contenido del nodo de ZooKeeper en /path/to/node. Esto también funciona si almacena un subárbol XML completo como un nodo de ZooKeeper; se insertará íntegramente en el elemento de origen.

Cambió en la versión 26.8: antes de esa versión, el archivo /etc/metrika.xml se usaba implícitamente siempre que existía, incluso cuando no se especificaba include_from. Si depende de ese archivo, especifique explícitamente su ruta en include_from. Tenga en cuenta que include_from se lee de cada archivo de configuración individualmente: los archivos que se cargan por separado de la configuración principal del servidor —la configuración de usuarios (por ejemplo, users.xml cuando no está incluido en el archivo principal) y las configuraciones de diccionarios XML— necesitan cada uno su propio elemento include_from; especificarlo solo en la configuración principal del servidor no se aplica a ellos.

A continuación se muestra un ejemplo:

<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>

Si desea combinar el contenido sustituido con la configuración existente en lugar de añadirlo, puede usar el atributo merge="true". Por ejemplo: <include from_zk="/some_path" merge="true">. En este caso, la configuración existente se combinará con el contenido de la sustitución y los valores de configuración existentes se reemplazarán por los de la sustitución.

Cifrado y ocultación de la configuración

Puede usar cifrado simétrico para cifrar un elemento de configuración, por ejemplo, una contraseña en texto plano o una clave privada. Para ello, primero configure el codec de cifrado y, a continuación, añada al elemento que desea cifrar el atributo encrypted_by, con el nombre del codec de cifrado como valor. A diferencia de los atributos from_zk, from_env e incl, o del elemento include, en el archivo preprocesado no se realiza ninguna sustitución (es decir, el descifrado del valor cifrado). El descifrado solo se produce en tiempo de ejecución, dentro del proceso del servidor. Por ejemplo:

<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>

Los atributos from_env y from_zk también se pueden aplicar a encryption_codecs:

<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>

Las claves de cifrado y los valores cifrados pueden definirse en cualquiera de los dos archivos de configuración. A continuación, se muestra un ejemplo de config.xml:

<clickhouse>

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

</clickhouse>

A continuación se muestra un ejemplo de users.xml:

<clickhouse>

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

</clickhouse>

Para cifrar un valor, puede usar el programa (de ejemplo) encrypt_decrypt:

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

961F000000040000000000EEDDEF4F453CFE6457C4234BD7C09258BD651D85

Incluso con elementos de configuración cifrados, estos siguen apareciendo en el archivo de configuración preprocesado. Si esto supone un problema para su implementación de ClickHouse, hay dos alternativas: o bien establecer los permisos del archivo preprocesado en 600, o usar el atributo hide_in_preprocessed. Por ejemplo:

<clickhouse>

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

</clickhouse>

Configuración de usuarios

El archivo config.xml puede especificar una configuración independiente con ajustes de usuario, perfiles y cuotas. La ruta relativa a esta configuración se establece en el elemento users_config. De forma predeterminada, es users.xml. Si se omite users_config, los ajustes de usuario, los perfiles y las cuotas se especifican directamente en config.xml. La configuración de usuarios puede dividirse en archivos independientes, de forma similar a config.xml y config.d/. El nombre del directorio se define como la opción users_config sin el sufijo .xml, concatenada con .d. El directorio users.d se usa de forma predeterminada, ya que users_config tiene como valor predeterminado users.xml. Los fragmentos de configuración de usuarios se combinan en orden lexicográfico según sus rutas completas. Para los archivos del directorio estándar users.d/, esto equivale a ordenarlos por nombre de archivo. El directorio heredado conf.d/ también se combina; dado que conf.d se ordena antes que users.d, todos sus fragmentos se procesan primero cuando existen ambos directorios. Tenga en cuenta que los archivos de configuración primero se combinan teniendo en cuenta la configuración, y después se procesan las inclusiones.

Ejemplo de XML

Por ejemplo, puede tener un archivo de configuración independiente para cada usuario, así:

$ 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>

Ejemplos de YAML

Aquí puede ver la configuración predeterminada escrita en YAML: config.yaml.example. Hay algunas diferencias entre los formatos YAML y XML en lo que respecta a las configuraciones de ClickHouse. A continuación, se presentan algunos consejos para escribir configuraciones en formato YAML. Una etiqueta XML con un valor de texto se representa como un par clave-valor en YAML

key: value

XML correspondiente:

<key>value</key>

Un nodo XML anidado se representa mediante un mapa YAML:

map_key:
  key1: val1
  key2: val2
  key3: val3

XML correspondiente:

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

Para crear varias veces la misma etiqueta XML, usa una secuencia YAML:

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

XML correspondiente:

<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>

Para indicar un atributo XML, puede usar una clave de atributo con el prefijo @. Tenga en cuenta que @ está reservado por el estándar YAML, por lo que debe ir entre comillas dobles:

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

XML correspondiente:

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

También es posible usar atributos en una secuencia YAML:

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

XML correspondiente:

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

La sintaxis mencionada anteriormente no permite expresar en YAML nodos de texto XML con atributos XML. Este caso especial se puede lograr con una clave de atributo #text:

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

XML correspondiente:

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

Detalles de implementación

Para cada archivo de configuración, el servidor también genera archivos file-preprocessed.xml al iniciarse. Estos archivos contienen todas las sustituciones y anulaciones resueltas, y están pensados para uso informativo. Si se usaron sustituciones de ZooKeeper en los archivos de configuración, pero ZooKeeper no está disponible cuando se inicia el servidor, el servidor carga la configuración desde el archivo preprocesado. El servidor realiza un seguimiento de los cambios en los archivos de configuración, así como en los archivos y nodos de ZooKeeper que se usaron al realizar sustituciones y anulaciones, y vuelve a cargar sobre la marcha la configuración de los usuarios y los clústeres. Esto significa que puede modificar el clúster, los usuarios y su configuración sin reiniciar el servidor.

Fundamentos

Conceptos de ClickHouse

Buenas prácticas

Combinación de archivos de configuración

Sustitución por variables de entorno y nodos de ZooKeeper

Cómo se interpretan los valores

Valores predeterminados

Sustitución con contenido de archivos

Cifrado y ocultación de la configuración

Configuración de usuarios

Ejemplo de XML

Ejemplos de YAML

Detalles de implementación

​Combinación de archivos de configuración

​Sustitución por variables de entorno y nodos de ZooKeeper

​Cómo se interpretan los valores

​Valores predeterminados

​Sustitución con contenido de archivos

​Cifrado y ocultación de la configuración

​Configuración de usuarios

​Ejemplo de XML

​Ejemplos de YAML

​Detalles de implementación

Combinación de archivos de configuración

Sustitución por variables de entorno y nodos de ZooKeeper

Cómo se interpretan los valores

Valores predeterminados

Sustitución con contenido de archivos

Cifrado y ocultación de la configuración

Configuración de usuarios

Ejemplo de XML

Ejemplos de YAML

Detalles de implementación