protocole composable

Les protocoles composables permettent une configuration plus souple de l’accès TCP au serveur ClickHouse. Cette configuration peut coexister avec la configuration classique ou la remplacer.

Les protocoles composables peuvent être configurés dans un fichier de configuration XML. La section protocols du fichier de configuration XML correspond à la section des protocoles :

<protocols>

</protocols>

Vous pouvez définir des couches de protocole à l’aide de modules de base. Par exemple, pour définir une couche HTTP, vous pouvez ajouter un nouveau module de base dans la section protocols :

<protocols>

  <!-- plain_http module -->
  <plain_http>
    <type>http</type>
  </plain_http>

</protocols>

Les modules peuvent être configurés comme suit :

• plain_http - nom auquel une autre couche peut faire référence
• type - indique le gestionnaire de protocole qui sera instancié pour traiter les données. Il peut prendre les gestionnaires de protocole prédéfinis suivants :
  • tcp - gestionnaire du protocole natif ClickHouse
  • http - gestionnaire du protocole HTTP ClickHouse
  • tls - couche de chiffrement TLS
  • proxy1 - couche PROXYv1
  • mysql - gestionnaire du protocole de compatibilité MySQL
  • postgres - gestionnaire du protocole de compatibilité PostgreSQL
  • prometheus - gestionnaire du protocole Prometheus
  • interserver - gestionnaire interserver ClickHouse

Les points de terminaison (ports d’écoute) sont indiqués par les balises facultatives <port> et <host>. Par exemple, pour configurer un point de terminaison sur la couche HTTP ajoutée précédemment, nous pourrions modifier notre configuration comme suit :

<protocols>

  <plain_http>

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

  </plain_http>

</protocols>

Si la balise <host> est absente, le <listen_host> de la configuration racine est utilisé.

Les séquences de couches sont définies à l’aide de la balise <impl>, en faisant référence à un autre module. Par exemple, pour configurer une couche TLS au-dessus de notre module plain_http, nous pourrions modifier davantage notre configuration comme suit :

<protocols>

  <!-- http module -->
  <plain_http>
    <type>http</type>
  </plain_http>

  <!-- https module configured as a tls layer on top of plain_http module -->
  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>

Des points de terminaison peuvent être associés à n’importe quelle couche. Par exemple, nous pouvons définir des points de terminaison pour HTTP (port 8123) et HTTPS (port 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>

Des points de terminaison supplémentaires peuvent être définis en faisant référence à n’importe quel module et en omettant la balise <type>. Par exemple, nous pouvons définir le point de terminaison another_http pour le module plain_http comme suit :

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

Par défaut, toutes les entrées de protocole type=http partagent la même configuration <http_handlers>. Vous pouvez remplacer ce comportement en ajoutant une balise <handlers> qui pointe vers une autre section de configuration. Cela permet à chaque port HTTP d'utiliser un ensemble différent de règles de routage HTTP.

Par exemple, pour exécuter une API HTTP alternative sur le port 8124 avec ses propres gestionnaires :

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

Dans cet exemple, les requêtes vers le port 8123 utilisent les règles standard de <http_handlers>, tandis que les requêtes vers le port 8124 utilisent les règles de <http_handlers_alt>. Si <handlers> est omis, le point de terminaison revient à <http_handlers> par défaut.

La section des handlers personnalisés suit le même format que <http_handlers>. Les modifications apportées à la section des handlers personnalisés sont détectées lors du rechargement de la config, et le point de terminaison correspondant est automatiquement redémarré.

Lorsqu’un client se connecte sans spécifier de nom d’utilisateur (par exemple, une requête HTTP sans le paramètre user, ou un paquet Hello du protocole natif avec un nom d’utilisateur vide), le serveur l’authentifie en tant qu’utilisateur de session par défaut : le paramètre du serveur default_session_user, dont la valeur par défaut est default.

La balise <default_session_user> surcharge ce paramètre pour un point de terminaison donné. Cela permet à différents ports d’écoute de servir différents utilisateurs anonymes :

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

Dans cet exemple, les requêtes sans informations d'identification sur le port 8123 sont authentifiées en tant qu' utilisateur de session default configuré globalement, tandis que celles sur le port 8124 sont authentifiées en tant que readonly_user. Un client qui fournit explicitement un nom d'utilisateur n'est pas concerné.

Le tag est recherché du module du point de terminaison vers les modules (impl) référencés, et la valeur la plus proche du point de terminaison l'emporte. Il s'applique aux gestionnaires de protocole tcp, http, mysql et postgres, ainsi qu'aux gestionnaires prometheus qui authentifient les requêtes (remote_write, remote_read, query et api_v1) ; les points de terminaison d'exposition des métriques (y compris les points de terminaison Keeper dédiés aux métriques uniquement) sont servis sans authentification et ignorent ce paramètre. Les gestionnaires avec un utilisateur fixe (la clé user dans handler d'une règle http_handlers, ou la clé user dans handler d'une règle prometheus.handlers) s'authentifient avec l'utilisateur configuré et ignorent également ce paramètre : en particulier, un default_session_user vide ne les rejette pas. Ce paramètre ne peut pas être utilisé avec le protocole interserver : les connexions interserveur sont authentifiées à l'aide du secret du cluster et de l'utilisateur initial, et n'utilisent jamais l'utilisateur de session default.

Certains modules peuvent inclure des paramètres de couche supplémentaires. Par exemple, la couche TLS permet de spécifier un fichier de clé privée (privateKeyFile) et un fichier de certificat (certificateFile) comme suit :

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