Replica-aware 라우팅

Replica-aware 라우팅(스티키 세션, 스티키 라우팅 또는 세션 어피니티라고도 함)은 관련 요청을 동일한 ClickHouse 레플리카로 라우팅합니다. 쿼리 간에도 임시 테이블 또는 이름이 지정된 세션 상태에 계속 액세스해야 하거나, 관련 쿼리에서 동일한 레플리카의 로컬 캐시를 재사용하려는 경우 또는 쓰기 후 후속 읽기에서 쓰기 후 읽기 일관성이 필요한 경우 사용하십시오. 이 기능은 최선의 노력 방식으로 작동하며 격리를 보장하지 않습니다. 프록시는 각 라우팅 값을 하나의 레플리카에 매핑합니다. 레플리카 수가 변경되지 않는 한 이 매핑은 유지됩니다. 서비스를 스케일링하면 해당 값이 다른 레플리카에 매핑될 수 있습니다. Replica-aware 라우팅은 다음 두 인터페이스 모두에서 사용할 수 있습니다.

HTTP/HTTPS에서는 X-ClickHouse-Replica-Tag 헤더를 사용합니다.
네이티브 프로토콜에서는 TLS Server Name Indication(SNI) 재정의를 사용합니다.

두 방식은 각각 별도로 활성화되며, 프록시 뒤에서 동일한 일관된 해싱을 사용합니다.

사전 요구 사항

서비스에는 2개 이상의 레플리카가 필요합니다. 레플리카가 1개뿐인 서비스에서는 고정할 대상이 없습니다.
Enterprise 티어 서비스여야 합니다.
표준 ClickHouse Cloud 서비스와 BYOC에서 지원됩니다.

Replica-aware 라우팅 구성

Enterprise 고객은 ClickHouse Cloud 콘솔의 서비스 설정 페이지에서 Replica-aware 라우팅을 활성화할 수 있습니다. 서비스를 연 다음 Settings로 이동하여 사용하려는 인터페이스의 토글을 켜십시오:

한 토글은 X-ClickHouse-Replica-Tag 헤더를 사용하는 HTTP 기반 라우팅을 활성화합니다.
다른 토글은 SNI 재정의를 사용하는 네이티브 프로토콜 라우팅을 활성화합니다.

둘 중 하나만 켜거나 둘 다 켤 수 있습니다. 재시작은 필요하지 않으며, 적용까지 1분이 채 걸리지 않습니다. 이 토글은 Enterprise tier 요금제 전반에 순차적으로 배포되고 있습니다. 아직 해당 서비스에 표시되지 않는다면, 서비스 ID를 포함해 support 티켓을 등록하여 기능을 더 빨리 활성화하도록 요청하십시오.

HTTP 기반 라우팅

워크로드를 특정 레플리카에 고정하려면 HTTPS 인터페이스를 통해 X-ClickHouse-Replica-Tag 헤더를 전송하십시오. 프록시는 헤더 값에 일관된 해싱을 적용하므로 레플리카 수가 변하지 않는 한 동일한 값을 사용하는 요청은 같은 레플리카로 전송됩니다. 다른 값은 독립적으로 해싱되며 같은 레플리카 또는 다른 레플리카에 할당될 수 있지만, 값이 어느 레플리카에 매핑될지는 선택할 수 없습니다. 기존 서비스 호스트명을 사용하십시오. 별도의 sticky 호스트명이나 DNS 변경은 필요하지 않습니다. 헤더 값에는 애플리케이션 이름, 사용자 ID 또는 워크로드 레이블 등 원하는 문자열을 사용할 수 있습니다. 헤더가 없는 요청에는 일반적인 부하 분산이 적용됩니다. 각 요청에 X-ClickHouse-Replica-Tag 헤더를 설정하십시오:

echo 'SELECT hostName()' | curl \
  -H 'X-ClickHouse-Replica-Tag: my-workload-1' \
  -H 'X-ClickHouse-User: default' \
  -H 'X-ClickHouse-Key: <password>' \
  'https://<host>:8443/' -d @-

clickhouse-go(v2)의 경우 Protocol: clickhouse.HTTP를 설정하고 HttpHeaders 연결 옵션을 통해 헤더를 전달하십시오.

X-ClickHouse-Replica-Tag를 사용하면 ClickHouse HTTP 세션을 생성하지 않고도 특정 레플리카에 요청을 고정할 수 있습니다. 동시에 실행되는 요청에서도 SESSION_IS_LOCKED 오류 없이 동일한 태그를 재사용할 수 있습니다.

네이티브 프로토콜 라우팅

네이티브 프로토콜을 사용할 때는 라우팅 값을 <routing-value>.sticky.<host> 형식의 TLS 서버 이름으로 전달합니다. 연결은 평소와 같이 일반 서비스 호스트명으로 수행하면 됩니다. ClickHouse Client는 --tls-sni-override로 라우팅 값을 전달받습니다:

clickhouse client \
  --host <host> \
  --secure \
  --tls-sni-override my-workload-1.sticky.<host> \
  --query 'SELECT hostName()'

--host는 일반적인 서비스 호스트명이고, --secure는 TLS를 활성화하며, --tls-sni-override는 라우팅 값을 전달합니다. TLS는 필수입니다. 별도의 인증서나 DNS 항목은 필요하지 않습니다.

읽기 후 쓰기 일관성(Read-after-write consistency)

멀티 레플리카 서비스에서는 한 레플리카에 수행한 쓰기가 복제가 완료되기 전까지 다른 레플리카에서 보이지 않을 수 있습니다. 쓰기 요청을 보낼 때 라우팅 값을 함께 지정하고, 이어지는 읽기에서 동일한 값을 재사용하십시오. 프록시가 두 요청을 같은 레플리카로 라우팅하므로, 다른 레플리카가 아직 뒤처져 있더라도 자신이 수행한 쓰기를 그대로 읽을 수 있습니다. 이 패턴은 데이터를 쓴 직후 동일한 데이터를 다시 읽는 워크로드, 예를 들어 대화형 애플리케이션이나 삽입 결과를 검사한 후 다음 단계로 진행하는 ETL 작업에 적합합니다. 또한 아직 복제되지 않은 스키마 변경 이후에도 유용합니다. 라우팅 값을 재사용하면 이미 새 스키마가 적용된 레플리카로 삽입이 계속 전달되기 때문입니다. HTTP를 사용하는 경우 헤더 값을 재사용하십시오:

# Write, tagged with a routing value
echo "INSERT INTO events VALUES (now(), 'signup')" | curl \
  -H 'X-ClickHouse-Replica-Tag: my-workload-1' \
  -H 'X-ClickHouse-User: default' \
  -H 'X-ClickHouse-Key: <password>' \
  'https://<host>:8443/' -d @-

# Read it back on the same replica, using the same value
echo 'SELECT count() FROM events' | curl \
  -H 'X-ClickHouse-Replica-Tag: my-workload-1' \
  -H 'X-ClickHouse-User: default' \
  -H 'X-ClickHouse-Key: <password>' \
  'https://<host>:8443/' -d @-

네이티브 프로토콜에서는 SNI 재정의를 그대로 사용합니다:

# Write with a routing value
clickhouse client \
  --host <host> \
  --secure \
  --tls-sni-override my-workload-1.sticky.<host> \
  --query "INSERT INTO events VALUES (now(), 'signup')"

# Read it back on the same replica, using the same value
clickhouse client \
  --host <host> \
  --secure \
  --tls-sni-override my-workload-1.sticky.<host> \
  --query 'SELECT count() FROM events'

모든 레플리카에 걸쳐 더 폭넓은 보장이 필요하다면, ClickHouse Cloud에서 select_sequential_consistency를 1로 설정할 수도 있습니다.

연결된 레플리카 확인

동일한 라우팅 값으로 SELECT hostName() 예시 중 하나를 다시 실행하십시오. 레플리카 수가 변경되지 않았다면 동일한 호스트명이 반환됩니다. 다른 라우팅 값은 다른 레플리카에 매핑될 수 있습니다.

Replica-aware 라우팅의 한계

레플리카 수가 변경되면 고정 연결도 변경됩니다

스케일 아웃 또는 스케일 인은 라우팅 hash ring을 변경합니다. 그러면 동일한 라우팅 값을 공유하는 요청이 다른 레플리카로 전달될 수 있습니다. 임시 테이블이나 세션 수준 설정에 의존하는 경우, 리매핑 후 이를 다시 생성할 수 있도록 준비하십시오. SELECT hostName()을 사용하면 현재 어느 레플리카에 연결되어 있는지 항상 확인할 수 있습니다.

Replica-aware 라우팅은 워크로드 격리가 아닙니다

스티키 라우팅은 어느 레플리카가 요청을 처리할지만 제어합니다. 해당 레플리카는 여전히 다른 트래픽도 처리할 수 있습니다. 전용 컴퓨트가 필요하면 컴퓨트-컴퓨트 분리를 사용하십시오.

프라이빗 네트워킹

HTTP 기반 라우팅과 네이티브 프로토콜 라우팅 모두 일반 서비스 호스트명에서 프라이빗 네트워킹과 함께 작동합니다. 추가 DNS 항목은 필요하지 않습니다.

네이티브 프로토콜 라우팅에는 TLS가 필요합니다

네이티브 프로토콜 라우팅에는 TLS가 필요하므로 --secure 옵션을 지정하십시오. 암호화되지 않은 네이티브 연결은 기존의 일반 로드 밸런싱 방식을 그대로 사용합니다.

문제 해결

동일한 라우팅 값을 사용했는데도 쿼리가 계속 다른 레플리카로 전달되는 경우

사용 중인 인터페이스에 대한 토글이 서비스 설정 페이지에서 활성화되어 있는지 확인하세요. HTTP 방식과 네이티브 방식은 각각 별도로 활성화됩니다.
HTTP를 사용하는 경우, 모든 요청에 X-ClickHouse-Replica-Tag 헤더가 포함되어 있고 모든 요청이 정확히 동일한 값을 사용하는지 확인하세요.
네이티브 프로토콜을 사용하는 경우, --secure가 설정되어 있고 --tls-sni-override가 <routing-value>.sticky.<host> 형식인지 확인하세요.
활성화 후 잠시 기다리세요. 적용되기까지 1분 이내가 걸릴 수 있습니다.
최근 레플리카 수가 변경되었는지 확인하세요. 스케일링 후에는 리매핑이 발생할 수 있습니다. SELECT hostName()을 사용하여 새 매핑을 확인하세요.

네이티브 프로토콜에서 인증서 오류가 발생하는 경우

--host가 일반 서비스 호스트명인지, 그리고 라우팅 값이 --host가 아닌 --tls-sni-override를 통해 전달되는지 확인하세요.

시작하기

서비스 및 인프라

Bring Your Own Cloud

데이터 및 통합

연결 및 쿼리 실행

접근 관리

보안 및 컴플라이언스

모니터링 및 백업

AI 도구 및 에이전트

Cloud API

청구

지원

ClickHouse Private

사전 요구 사항

Replica-aware 라우팅 구성

HTTP 기반 라우팅

네이티브 프로토콜 라우팅

읽기 후 쓰기 일관성(Read-after-write consistency)

연결된 레플리카 확인

Replica-aware 라우팅의 한계

레플리카 수가 변경되면 고정 연결도 변경됩니다

Replica-aware 라우팅은 워크로드 격리가 아닙니다

프라이빗 네트워킹

네이티브 프로토콜 라우팅에는 TLS가 필요합니다

문제 해결

​사전 요구 사항

​Replica-aware 라우팅 구성

​HTTP 기반 라우팅

​네이티브 프로토콜 라우팅

​읽기 후 쓰기 일관성(Read-after-write consistency)

​연결된 레플리카 확인

​Replica-aware 라우팅의 한계

​레플리카 수가 변경되면 고정 연결도 변경됩니다

​Replica-aware 라우팅은 워크로드 격리가 아닙니다

​프라이빗 네트워킹

​네이티브 프로토콜 라우팅에는 TLS가 필요합니다

​문제 해결

사전 요구 사항

Replica-aware 라우팅 구성

HTTP 기반 라우팅

네이티브 프로토콜 라우팅

읽기 후 쓰기 일관성(Read-after-write consistency)

연결된 레플리카 확인

Replica-aware 라우팅의 한계

레플리카 수가 변경되면 고정 연결도 변경됩니다

Replica-aware 라우팅은 워크로드 격리가 아닙니다

프라이빗 네트워킹

네이티브 프로토콜 라우팅에는 TLS가 필요합니다

문제 해결