Protocolos componibles

Los protocolos componibles permiten una configuración más flexible del acceso TCP al servidor de ClickHouse. Esta configuración puede coexistir con la configuración convencional o reemplazarla.

Los protocolos componibles se pueden configurar en un archivo de configuración XML. La sección de protocolos se indica con etiquetas protocols en el archivo de configuración XML:

<protocols>

</protocols>

Puede definir capas de protocolo con módulos básicos. Por ejemplo, para definir una capa HTTP, puede añadir un módulo básico nuevo a la sección protocols:

<protocols>

  <!-- módulo plain_http -->
  <plain_http>
    <type>http</type>
  </plain_http>

</protocols>

Los módulos se pueden configurar de la siguiente manera:

• plain_http - nombre al que puede hacer referencia otra capa
• type - indica el manejador de protocolo que se instanciará para procesar datos. Tiene el siguiente conjunto de manejadores de protocolo predefinidos:
  • tcp - manejador del protocolo nativo de ClickHouse
  • http - manejador del protocolo HTTP de ClickHouse
  • tls - capa de cifrado TLS
  • proxy1 - capa PROXYv1
  • mysql - manejador del protocolo de compatibilidad con MySQL
  • postgres - manejador del protocolo de compatibilidad con Postgres
  • prometheus - manejador del protocolo Prometheus
  • interserver - manejador interserver de ClickHouse

Los endpoints (puertos de escucha) se indican con las etiquetas <port> y, opcionalmente, <host>. Por ejemplo, para configurar un endpoint en la capa HTTP añadida anteriormente, podríamos modificar la configuración de la siguiente manera:

<protocols>

  <plain_http>

    <type>http</type>
    <!-- endpoint -->
    <host>127.0.0.1</host>
    <port>8123</port>

  </plain_http>

</protocols>

Si se omite la etiqueta <host>, se usa <listen_host> de la configuración principal.

Las secuencias de capas se definen con la etiqueta <impl> y haciendo referencia a otro módulo. Por ejemplo, para configurar una capa TLS sobre nuestro módulo plain_http, podríamos seguir modificando nuestra configuración de la siguiente manera:

<protocols>

  <!-- módulo http -->
  <plain_http>
    <type>http</type>
  </plain_http>

  <!-- módulo https configurado como una capa TLS sobre el módulo plain_http -->
  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>

Los endpoints se pueden asociar a cualquier capa. Por ejemplo, podemos definir endpoints para HTTP (puerto 8123) y HTTPS (puerto 8443):

<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>

Los endpoints adicionales pueden definirse haciendo referencia a cualquier módulo y omitiendo la etiqueta <type>. Por ejemplo, podemos definir el endpoint another_http para el módulo plain_http de la siguiente manera:

<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

  <another_http>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8223</port>
  </another_http>

</protocols>

De forma predeterminada, todas las entradas de protocolo type=http comparten la misma configuración <http_handlers>. Puede cambiar esto añadiendo una etiqueta <handlers> que apunte a una sección de configuración distinta. Esto permite que cada puerto HTTP sirva un conjunto diferente de reglas de enrutamiento HTTP.

Por ejemplo, para ejecutar una API HTTP alternativa en el puerto 8124 con sus propios handler:

<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <alt_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8124</port>
    <handlers>http_handlers_alt</handlers>
  </alt_http>

</protocols>

<!-- Default handlers used by plain_http (port 8123) -->
<http_handlers>
    <defaults/>
</http_handlers>

<!-- Alternative handlers used by alt_http (port 8124) -->
<http_handlers_alt>
    <rule>
        <url>/custom</url>
        <handler>
            <type>predefined_query_handler</type>
            <query>SELECT 'custom_endpoint'</query>
        </handler>
    </rule>
    <defaults/>
</http_handlers_alt>

En este ejemplo, las solicitudes al puerto 8123 usan las reglas estándar de <http_handlers>, mientras que las solicitudes al puerto 8124 usan las reglas de <http_handlers_alt>. Si se omite <handlers>, el endpoint vuelve al valor predeterminado <http_handlers>.

La sección de handler personalizados sigue el mismo formato que <http_handlers>. Los cambios en la sección de handler personalizados se detectan durante la recarga de la configuración, y el endpoint correspondiente se reinicia automáticamente.

Cuando un cliente se conecta sin especificar un nombre de usuario (por ejemplo, mediante una solicitud HTTP sin el parámetro user o un paquete Hello del protocolo nativo con un nombre de usuario vacío), el servidor lo autentica como el usuario de sesión predeterminado: el ajuste del servidor default_session_user, cuyo valor predeterminado es default.

La etiqueta <default_session_user> sobrescribe este ajuste para un único endpoint. Esto permite que distintos puertos de escucha atiendan a diferentes usuarios anónimos:

<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <readonly_http>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8124</port>
    <default_session_user>readonly_user</default_session_user>
  </readonly_http>

</protocols>

En este ejemplo, las solicitudes sin credenciales en el puerto 8123 se autentican como el usuario de sesión predeterminado configurado globalmente, mientras que las del puerto 8124 se autentican como readonly_user. Un client que proporciona explícitamente un nombre de usuario no se ve afectado.

La etiqueta se busca desde el módulo del endpoint hacia los módulos (impl) a los que hace referencia, y prevalece el valor más cercano al endpoint. Se aplica a los handlers de protocolo tcp, http, mysql y postgres, así como a los handlers de prometheus que autentican solicitudes (remote_write, remote_read, query y api_v1); los endpoints de exposición de métricas (incluidos los endpoints de Keeper exclusivos para métricas) se sirven sin autenticación e ignoran esta configuración. Los handlers con un usuario fijo (la clave user dentro de handler de una regla http_handlers, o la clave user dentro de handler de una regla prometheus.handlers) se autentican como el usuario configurado y también ignoran esta configuración; en particular, un default_session_user vacío no los rechaza. No se puede utilizar con el protocolo interserver: las conexiones entre servidores se autentican mediante el secreto del cluster y el usuario inicial, y nunca usan el usuario de sesión predeterminado.

Algunos módulos pueden incluir parámetros adicionales de la capa. Por ejemplo, la capa TLS permite especificar una clave privada (privateKeyFile) y archivos de certificado (certificateFile) de la siguiente manera:

<protocols>

  <plain_http>
    <type>http</type>
    <host>127.0.0.1</host>
    <port>8123</port>
  </plain_http>

  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
    <privateKeyFile>another_server.key</privateKeyFile>
    <certificateFile>another_server.crt</certificateFile>
  </https>

</protocols>