컴포저블 프로토콜(Composable Protocols)

컴포저블 프로토콜(Composable Protocols)

컴포저블 프로토콜은 ClickHouse 서버에 대한 TCP 접근을 더 유연하게 구성할 수 있게 해 줍니다. 이 문서에서는 프로토콜 레이어와 엔드포인트를 XML로 구성하는 방법을 예제와 함께 설명할게요.

출처: 문서

본문

개요

컴포저블 프로토콜은 ClickHouse 서버에 대한 TCP 접근을 더 유연하게 구성할 수 있게 합니다. 이 구성은 기존 구성과 함께 공존하거나, 기존 구성을 대체할 수 있습니다.

컴포저블 프로토콜 구성하기

컴포저블 프로토콜은 XML 설정 파일에서 구성할 수 있습니다. protocols 섹션은 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 프로토콜 핸들러는 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> 태그를 사용해 다른 모듈을 참조하여 정의됩니다. 예를 들어 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>

<!-- plain_http(포트 8123)가 사용하는 기본 핸들러 -->
<http_handlers>
    <defaults/>
</http_handlers>

<!-- alt_http(포트 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_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 메트릭 전용 엔드포인트 포함)는 인증 없이 서비스되며 이 설정을 무시합니다. 고정 사용자가 있는 핸들러(http_handlers 규칙의 handler 안의 user 키, 또는 prometheus.handlers 규칙의 handler 안의 user 키)는 구성된 사용자로 인증하고 이 설정도 무시합니다 — 특히 빈 default_session_user는 그들을 거부하지 않습니다. interserver 프로토콜에는 사용할 수 없습니다. 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>

더 알아보기 (Learn more)