コンポーザブルプロトコル

概要

コンポーザブルプロトコルを使用すると、ClickHouseサーバーへの TCP アクセスをより柔軟に構成できます。この構成は、従来の構成と併用することも、置き換えることもできます。

コンポーザブルプロトコルの設定

コンポーザブルプロトコルは、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のinterserverハンドラー

gRPC プロトコルハンドラーは コンポーザブルプロトコル では実装されていません

エンドポイントの設定

エンドポイント (待ち受けポート) は、<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> タグを使って定義し、別のモジュールを参照することで構成します。たとえば、plain_http モジュールの上に TLS レイヤーを設定するには、設定をさらに次のように変更できます。

<protocols>

  <!-- httpモジュール -->
  <plain_http>
    <type>http</type>
  </plain_http>

  <!-- plain_httpモジュールの上にTLSレイヤーとして設定されたhttpsモジュール -->
  <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> タグを省略することで、追加のエンドポイントを定義できます。たとえば、plain_http モジュールに対する another_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 ルーティングルールのセットを提供できます。たとえば、ポート 8124 で独自のハンドラーを持つ別の HTTP API を実行するには:

<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> と同じ形式です。カスタムハンドラーのセクションへの変更は設定のリロード時に検出され、対応するエンドポイントは自動的に自動的に再起動されます。

エンドポイントごとのデフォルトセッションユーザー

クライアントがユーザー名を指定せずに接続した場合 (たとえば、user パラメータなしの HTTP リクエストや、ユーザー名が空のネイティブプロトコル Hello パケット) 、サーバーはデフォルトセッションユーザーとして認証します。デフォルトセッションユーザーは、デフォルト値が default の default_session_user サーバー設定です。 <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のメトリクス専用エンドポイントを含む) は認証なしで提供され、この設定を無視します。固定ユーザーを持つハンドラー (http_handlersルールのhandler内のuserキー、またはprometheus.handlersルールのhandler内のuserキー) は、設定されたユーザーとして認証され、この設定も無視します。特に、default_session_userが空であっても、これらのハンドラーが拒否されることはありません。この設定はinterserverプロトコルでは使用できません。interserver接続はクラスターのsecretと初期ユーザーによって認証され、デフォルトのセッションユーザーを使用することはありません。

追加のレイヤーパラメータを指定する

一部のモジュールでは、追加のレイヤーパラメータを指定できます。たとえば、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>

基礎

ClickHouseの基本概念

ベストプラクティス

概要