Skip to main content
Replica-aware 라우팅(스티키 세션, 스티키 라우팅 또는 세션 어피니티라고도 함)은 관련 요청을 동일한 ClickHouse 레플리카로 라우팅합니다. 쿼리 간에도 임시 테이블 또는 이름이 지정된 세션 상태에 계속 액세스해야 하거나, 관련 쿼리에서 동일한 레플리카의 로컬 캐시를 재사용하려는 경우 또는 쓰기 후 후속 읽기에서 쓰기 후 읽기 일관성이 필요한 경우 사용하십시오. 이 기능은 최선의 노력 방식으로 작동하며 격리를 보장하지 않습니다. 프록시는 각 라우팅 값을 하나의 레플리카에 매핑합니다. 레플리카 수가 변경되지 않는 한 이 매핑은 유지됩니다. 서비스를 스케일링하면 해당 값이 다른 레플리카에 매핑될 수 있습니다.
HTTP 인터페이스 필요Replica-aware 라우팅은 HTTP/HTTPS 인터페이스를 통해 프록시 계층에서 적용됩니다. ClickHouse Cloud는 Replica-aware 라우팅 방식을 session_id에서 X-ClickHouse-Replica-Tag 헤더로 전환하고 있습니다. 아래 탭에서는 롤아웃 기간 동안 두 방법을 모두 설명합니다.Replica-aware 라우팅은 현재 네이티브 프로토콜에서 사용할 수 없습니다(네이티브 포트, 예: 기본 네이티브 모드의 clickhouse-go 드라이버). 네이티브 프로토콜 클라이언트는 HTTP로 전환하고 모든 요청에 라우팅 값을 전송해야 합니다.

​
사전 요구 사항

  • 서비스에는 2개 이상의 레플리카가 필요합니다. 레플리카가 1개뿐인 서비스에서는 고정할 대상이 없습니다.
  • 이 기능이 일반 제공되면 기본적으로 Enterprise에서 사용할 수 있습니다.
  • 표준 ClickHouse Cloud 서비스에서 지원됩니다. BYOC는 아직 지원되지 않습니다.

​
Replica-aware 라우팅 구성하기

지원 티켓을 열어 HTTP 기반 sticky 레플리카 라우팅을 활성화해 달라고 요청하십시오. 서비스 ID와 이 기능이 필요한 이유(임시 테이블, 세션 상태, 캐시 재사용 또는 쓰기 후 읽기 일관성)를 함께 포함하십시오. 기존 서비스를 마이그레이션하기 전에 지원팀에 해당 서비스에 header 기반 라우팅이 활성화되어 있는지 확인해 달라고 요청하십시오. 확인을 받을 때까지 session_id를 계속 사용하십시오. 배포가 서비스에 적용되기 전까지 X-ClickHouse-Replica-Tag는 sticky 라우팅을 제공하지 않습니다. 재시작은 필요하지 않습니다.

​
HTTP 기반 라우팅

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

​
쓰기 후 읽기 일관성

다중 레플리카 서비스에서는 한 레플리카에 쓴 데이터가 복제가 완료될 때까지 다른 레플리카에서 보이지 않을 수 있습니다. X-ClickHouse-Replica-Tag 헤더와 함께 쓰기 요청을 전송한 후, 후속 읽기 요청에서도 동일한 헤더 값을 재사용하십시오. 프록시가 두 요청을 동일한 레플리카로 라우팅하므로 다른 레플리카의 복제가 아직 완료되지 않았더라도 방금 쓴 데이터를 읽을 수 있습니다. 이 패턴은 대화형 애플리케이션이나 다음 단계로 진행하기 전에 삽입을 검증하는 ETL 작업처럼 데이터를 쓴 직후 동일한 데이터를 다시 읽는 워크로드에 적합합니다.모든 레플리카에 걸쳐 더 강력한 일관성을 보장하려면 ClickHouse Cloud에서 select_sequential_consistency를 1로 설정할 수도 있습니다.

​
연결된 레플리카 확인

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

​
레거시 하위 도메인 기반 라우팅

하위 도메인 기반 라우팅은 새로운 서비스에서 더 이상 활성화되지 않습니다. 이미 sticky 하위 도메인을 사용 중이라면 지원에 문의하여 HTTP 헤더 메서드로 마이그레이션하십시오.
이전에는 Replica-aware 라우팅을 활성화하면 서비스 호스트명에 와일드카드 하위 도메인을 추가로 사용할 수 있었습니다. 호스트명이 abcxyz123.us-west-2.aws.clickhouse.cloud인 서비스의 경우, *.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud(예: aaa.sticky.abcxyz123.us-west-2.aws.clickhouse.cloud)와 일치하는 모든 호스트명은 Envoy가 해시를 사용해 일관되게 특정 레플리카로 라우팅했습니다. 원래 호스트명은 기본 라우팅 알고리즘인 LEAST_CONNECTION load balancing을 계속 사용했습니다.

​
Replica-aware 라우팅의 한계

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

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

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

스티키 라우팅은 어느 레플리카가 요청을 처리할지만 제어합니다. 해당 레플리카는 여전히 다른 트래픽도 처리할 수 있습니다. 전용 컴퓨트가 필요하면 컴퓨트-컴퓨트 분리를 사용하십시오. HTTP 기반 라우팅은 일반 서비스 호스트명에서 프라이빗 네트워킹과 함께 작동합니다. 추가 DNS 항목은 필요하지 않습니다. 하지만 레거시 하위 도메인 방식은 그렇지 않습니다. *.sticky.* 호스트명 패턴에 대한 DNS를 추가해야 하며, 설정이 올바르지 않으면 레플리카 간 부하가 불균형하게 분산될 수 있습니다.

​
Replica-aware 라우팅에는 HTTP 프로토콜이 필요합니다

스티키 라우팅은 서비스에서 사용할 수 있는 라우팅 메서드에 따라 HTTP 헤더 또는 쿼리 매개변수를 기준으로 합니다. 네이티브 바이너리 프로토콜에는 HTTP 프록시가 해시에 사용할 수 있는 두 값이 없으므로, 네이티브 프로토콜을 통해서는 Replica-aware 라우팅을 사용할 수 없습니다. 네이티브 프로토콜을 사용하는 클라이언트는 이 기능을 사용하려면 관련 워크로드를 HTTP 인터페이스로 옮겨야 합니다.

​
문제 해결

동일한 라우팅 값을 사용했는데도 쿼리가 계속 다른 레플리카로 전달되는 경우
  • 서비스에서 지원하는 라우팅 메서드(X-ClickHouse-Replica-Tag 헤더 또는 레거시 session_id URL 쿼리 매개변수)를 사용하고 있는지 확인하세요.
  • 모든 요청에서 정확히 동일한 라우팅 값을 사용하는지 확인하세요.
  • 활성화 후 잠시 기다리세요. 적용되기까지 1분 이내가 걸릴 수 있습니다.
  • 최근 레플리카 수가 변경되었는지 확인하세요. 스케일링 후에는 리매핑이 발생할 수 있습니다. SELECT hostName()을 사용하여 새 매핑을 확인하세요.
마지막 수정일 2026년 8월 14일