Составные протоколы

Обзор

Составные протоколы позволяют более гибко настраивать TCP-доступ к серверу ClickHouse. Такая конфигурация может использоваться наряду с обычной или полностью её заменять.

Настройка составных протоколов

Составные протоколы можно настраивать в XML-файле конфигурации. Раздел протоколов в XML-файле конфигурации обозначается тегами protocols:

<protocols>

</protocols>

Настройка уровней протокола

Вы можете задавать уровни протокола с помощью базовых модулей. Например, чтобы задать уровень HTTP, можно добавить новый базовый модуль в раздел protocols:

<protocols>

  <!-- модуль plain_http -->
  <plain_http>
    <type>http</type>
  </plain_http>

</protocols>

Модули можно настраивать с помощью следующих параметров:

plain_http - имя, на которое может ссылаться другой слой
type - указывает обработчик протокола, который будет создан для обработки данных. Доступен следующий набор предопределённых обработчиков протоколов:
- tcp - нативный обработчик протокола ClickHouse
- http - HTTP-обработчик протокола ClickHouse
- tls - слой шифрования TLS
- proxy1 - слой PROXYv1
- mysql - обработчик протокола совместимости с MySQL
- postgres - обработчик протокола совместимости с PostgreSQL
- prometheus - обработчик протокола Prometheus
- interserver - межсерверный обработчик ClickHouse

Обработчик протокола gRPC не реализован для Composable protocols

Настройка конечных точек

Конечные точки (прослушиваемые порты) обозначаются тегами <port> и необязательным тегом <host>. Например, чтобы настроить конечную точку на ранее добавленном HTTP-слое, мы можем изменить конфигурацию следующим образом:

<protocols>

  <plain_http>

    <type>http</type>
    <!-- конечная точка -->
    <host>127.0.0.1</host>
    <port>8123</port>

  </plain_http>

</protocols>

Если тег <host> не указан, используется <listen_host> из корневой конфигурации.

Настройка последовательностей слоёв

Последовательности слоёв определяются с помощью тега <impl> и ссылки на другой модуль. Например, чтобы настроить слой TLS поверх нашего модуля plain_http, мы можем дополнительно изменить конфигурацию следующим образом:

<protocols>

  <!-- модуль http -->
  <plain_http>
    <type>http</type>
  </plain_http>

  <!-- модуль https, настроенный как слой tls поверх модуля plain_http -->
  <https>
    <type>tls</type>
    <impl>plain_http</impl>
    <host>127.0.0.1</host>
    <port>8443</port>
  </https>

</protocols>

Подключение конечных точек к слоям

Конечные точки можно подключить к любому слою. Например, можно определить конечные точки для HTTP (порт 8123) и HTTPS (порт 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>

Определение дополнительных конечных точек

Дополнительные конечные точки можно задать, указав любой модуль и опустив тег <type>. Например, можно определить конечную точку another_http для модуля plain_http следующим образом:

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

Пользовательские HTTP-обработчики для отдельных конечных точек

По умолчанию все записи протокола type=http используют одну и ту же конфигурацию <http_handlers>. Это можно переопределить, добавив тег <handlers>, который ссылается на другой раздел конфигурации. Благодаря этому каждый HTTP-порт может обслуживать свой набор правил HTTP-маршрутизации. Например, чтобы запустить альтернативный HTTP API на порту 8124 с собственными обработчиками:

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

В этом примере запросы к порту 8123 используют стандартные правила <http_handlers>, а запросы к порту 8124 — правила <http_handlers_alt>. Если <handlers> не указан, конечная точка использует значение по умолчанию — <http_handlers>. Раздел пользовательских обработчиков имеет тот же формат, что и <http_handlers>. Изменения в разделе пользовательских обработчиков отслеживаются при перезагрузке конфигурации, и соответствующая конечная точка автоматически перезапускается.

Пользователь сеанса по умолчанию для каждой конечной точки

Если клиент подключается, не указав имя пользователя (например, в HTTP-запросе без параметра user или в пакете Hello собственного протокола с пустым именем пользователя), сервер аутентифицирует его как пользователя сеанса по умолчанию — default_session_user, настройку сервера со значением по умолчанию default. Тег <default_session_user> переопределяет эту настройку для отдельной конечной точки. Это позволяет разным прослушиваемым портам обслуживать разных анонимных пользователей:

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

В этом примере запросы без учетных данных на порту 8123 аутентифицируются от имени глобально настроенного пользователя сеанса по умолчанию, а на порту 8124 — от имени readonly_user. Клиент, явно указывающий имя пользователя, не затрагивается. Тег ищется от модуля конечной точки в направлении модулей, на которые ссылается impl, и приоритет имеет значение, расположенное ближе всего к конечной точке. Эта настройка применяется к обработчикам протоколов tcp, http, mysql и postgres, а также к обработчикам prometheus, которые аутентифицируют запросы (remote_write, remote_read, query и api_v1); конечные точки экспорта метрик (включая конечные точки Keeper, предоставляющие только метрики) обслуживаются без аутентификации и игнорируют эту настройку. Обработчики с фиксированным пользователем (ключ user внутри handler правила http_handlers или ключ user внутри handler правила prometheus.handlers) аутентифицируют запросы от имени настроенного пользователя и также игнорируют эту настройку — в частности, пустое значение default_session_user не приводит к их отклонению. Эту настройку нельзя использовать с протоколом interserver: межсерверные подключения аутентифицируются с помощью секрета кластера и начального пользователя и никогда не используют пользователя сеанса по умолчанию.

Указание дополнительных параметров слоя

Некоторые модули могут содержать дополнительные параметры слоя. Например, для слоя TLS можно указать закрытый ключ (privateKeyFile) и файлы сертификатов (certificateFile) следующим образом:

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

Fundamentals

ClickHouse concepts

Best practices

Обзор

Настройка составных протоколов

Настройка уровней протокола

Настройка конечных точек

Настройка последовательностей слоёв

Подключение конечных точек к слоям

Определение дополнительных конечных точек

Пользовательские HTTP-обработчики для отдельных конечных точек

Пользователь сеанса по умолчанию для каждой конечной точки

Указание дополнительных параметров слоя

​Обзор

​Настройка составных протоколов

​Настройка уровней протокола

​Настройка конечных точек

​Настройка последовательностей слоёв

​Подключение конечных точек к слоям

​Определение дополнительных конечных точек

​Пользовательские HTTP-обработчики для отдельных конечных точек

​Пользователь сеанса по умолчанию для каждой конечной точки

​Указание дополнительных параметров слоя

Обзор

Настройка составных протоколов

Настройка уровней протокола

Настройка конечных точек

Настройка последовательностей слоёв

Подключение конечных точек к слоям

Определение дополнительных конечных точек

Пользовательские HTTP-обработчики для отдельных конечных точек

Пользователь сеанса по умолчанию для каждой конечной точки

Указание дополнительных параметров слоя