Protocolos componíveis

Os protocolos componíveis permitem configurar com mais flexibilidade o acesso TCP ao servidor ClickHouse. Essa configuração pode coexistir com a configuração convencional ou substituí-la.

Os protocolos componíveis podem ser configurados em um arquivo de configuração XML. A seção de protocolos é definida pelas tags protocols no arquivo de configuração XML:

<protocols>

</protocols>

Você pode definir camadas de protocolo usando módulos base. Por exemplo, para definir uma camada HTTP, adicione um novo módulo base à seção protocols:

<protocols>

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

</protocols>

Os módulos podem ser configurados da seguinte forma:

• plain_http - nome ao qual outra camada pode fazer referência
• type - indica o handler de protocolo que será instanciado para processar dados. Ele tem o seguinte conjunto de handlers de protocolo predefinidos:
  • tcp - handler do protocolo nativo do ClickHouse
  • http - handler do protocolo HTTP do ClickHouse
  • tls - camada de criptografia TLS
  • proxy1 - camada PROXYv1
  • mysql - handler do protocolo de compatibilidade com MySQL
  • postgres - handler do protocolo de compatibilidade com PostgreSQL
  • prometheus - handler do protocolo Prometheus
  • interserver - handler de interservidor do ClickHouse

Os endpoints (portas de escuta) são representados pelas tags <port> e <host> opcionais. Por exemplo, para configurar um endpoint na camada HTTP adicionada anteriormente, poderíamos modificar nossa configuração da seguinte forma:

<protocols>

  <plain_http>

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

  </plain_http>

</protocols>

Se a tag <host> for omitida, será usada a <listen_host> da configuração raiz.

As sequências de camadas são definidas com a tag <impl>, fazendo referência a outro módulo. Por exemplo, para configurar uma camada TLS sobre o nosso módulo plain_http, podemos ajustar ainda mais a configuração da seguinte forma:

<protocols>

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

  <!-- módulo https configurado como uma camada TLS sobre o módulo plain_http -->
  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>

Endpoints podem ser associados a qualquer camada. Por exemplo, podemos definir endpoints para HTTP (porta 8123) e HTTPS (porta 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>

É possível definir endpoints adicionais referenciando qualquer módulo e omitindo a tag <type>. Por exemplo, podemos definir o endpoint another_http para o módulo plain_http da seguinte forma:

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

Por padrão, todas as entradas do protocolo type=http compartilham a mesma configuração <http_handlers>. Você pode sobrescrever isso adicionando uma tag <handlers> que aponta para outra seção de configuração. Isso permite que cada porta HTTP use um conjunto diferente de regras de roteamento HTTP.

Por exemplo, para executar uma API HTTP alternativa na porta 8124 com seus próprios handlers:

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

Neste exemplo, as requisições para a porta 8123 usam as regras padrão de <http_handlers>, enquanto as requisições para a porta 8124 usam as regras de <http_handlers_alt>. Se <handlers> for omitido, o endpoint volta para o <http_handlers> padrão.

A seção de handlers personalizados segue o mesmo formato de <http_handlers>. As alterações na seção de handlers personalizados são detectadas durante a recarga da configuração, e o endpoint correspondente é reiniciado automaticamente.

Quando um cliente se conecta sem especificar um nome de usuário (por exemplo, uma requisição HTTP sem o parâmetro user ou um pacote Hello do protocolo nativo com um nome de usuário vazio), o servidor o autentica como o usuário de sessão padrão — a configuração do servidor default_session_user, cujo valor padrão é default.

A tag <default_session_user> substitui essa configuração para um único endpoint. Isso permite que diferentes portas de escuta atendam a diferentes usuários 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>

Neste exemplo, as solicitações sem credenciais na porta 8123 são autenticadas como o usuário de sessão padrão configurado globalmente, enquanto as da porta 8124 são autenticadas como readonly_user. Um cliente que informa explicitamente um nome de usuário não é afetado.

A tag é pesquisada a partir do módulo do endpoint em direção aos módulos (impl) referenciados, e o valor mais próximo do endpoint prevalece. Ela se aplica aos handlers de protocolo tcp, http, mysql e postgres, bem como aos handlers prometheus que autenticam solicitações (remote_write, remote_read, query e api_v1); os endpoints de exposição de métricas (incluindo endpoints do Keeper exclusivos para métricas) são disponibilizados sem autenticação e ignoram a configuração. Handlers com um usuário fixo (a chave user dentro de handler de uma regra http_handlers, ou a chave user dentro de handler de uma regra prometheus.handlers) autenticam as solicitações como o usuário configurado e também ignoram a configuração — em particular, um default_session_user vazio não os rejeita. Ela não pode ser usada com o protocolo interservidor: as conexões interservidor são autenticadas pelo Secret do cluster e pelo usuário inicial e nunca usam o usuário de sessão padrão.

Alguns módulos podem conter parâmetros adicionais de camada. Por exemplo, a camada TLS permite especificar uma chave privada (privateKeyFile) e arquivos de certificado (certificateFile) da seguinte forma:

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