> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Replica-aware 라우팅

> 임시 테이블, 세션, 캐시 재사용 및 쓰기 후 읽기 일관성을 위해 관련 요청을 동일한 ClickHouse Cloud 레플리카로 라우팅합니다

export const EnterprisePlanFeatureBadge = ({feature = '이 기능', support = false, linking_verb_are = false}) => {
  return <div className="enterprisePlanFeatureContainer">
            <div className="enterprisePlanFeatureBadge">
                Enterprise 플랜 기능
            </div>
            <div>
                <p>{feature} {linking_verb_are ? '' : ''}Enterprise 플랜에서 사용할 수 있습니다. {support ? `이 기능을 활성화하려면 지원팀에 문의하십시오.` : '업그레이드하려면 Cloud Console의 요금제 페이지로 이동하십시오.'}</p>
            </div>
        </div>;
};

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'ClickHouse Cloud 비공개 프리뷰'}
        </div>;
};

<PrivatePreviewBadge />

<EnterprisePlanFeatureBadge feature="Replica-aware 라우팅" support="true" />

Replica-aware 라우팅(스티키 세션, 스티키 라우팅 또는 세션 어피니티라고도 함)은 관련 요청을 동일한 ClickHouse 레플리카로 라우팅합니다. 쿼리 간에도 [임시 테이블](/ko/reference/statements/create/table/temporary-table) 또는 [이름이 지정된 세션 상태](/ko/concepts/features/interfaces/http#using-clickhouse-sessions-in-the-http-protocol)에 계속 액세스해야 하거나, 관련 쿼리에서 동일한 레플리카의 로컬 캐시를 재사용하려는 경우 또는 쓰기 후 후속 읽기에서 [쓰기 후 읽기 일관성](#read-after-write-consistency)이 필요한 경우 사용하십시오.

이 기능은 최선의 노력 방식으로 작동하며 격리를 보장하지 않습니다. 프록시는 각 라우팅 값을 하나의 레플리카에 매핑합니다. 레플리카 수가 변경되지 않는 한 이 매핑은 유지됩니다. 서비스를 스케일링하면 해당 값이 다른 레플리카에 매핑될 수 있습니다.

<Warning>
  **HTTP 인터페이스 필요**

  Replica-aware 라우팅은 `X-ClickHouse-Replica-Tag` 헤더를 사용하여 [HTTP/HTTPS 인터페이스](/ko/concepts/features/interfaces/http)를 통해 프록시 계층에서 적용됩니다.

  Replica-aware 라우팅은 **현재 네이티브 프로토콜에서 사용할 수 없습니다**(네이티브 포트, 예: 기본 네이티브 모드의 [clickhouse-go](/ko/integrations/language-clients/go/index) 드라이버). 네이티브 프로토콜 클라이언트는 HTTP로 전환하고 모든 요청에 라우팅 값을 전송해야 합니다.
</Warning>

<div id="prerequisites">
  ## 사전 요구 사항
</div>

* 서비스에는 **2개 이상의 레플리카**가 필요합니다. 레플리카가 1개뿐인 서비스에서는 고정할 대상이 없습니다.
* 이 기능이 **일반 제공**되면 기본적으로 **Enterprise**에서 사용할 수 있습니다.
* 표준 ClickHouse Cloud 서비스에서 지원됩니다. [BYOC](/ko/products/cloud/guides/infrastructure/deployment-options/byoc/overview)는 아직 지원되지 않습니다.

<div id="configuring-replica-aware-routing">
  ## Replica-aware 라우팅 구성하기
</div>

[지원](https://clickhouse.com/support/program) 티켓을 열어 HTTP 기반 sticky 레플리카 라우팅을 활성화해 달라고 요청하십시오. 서비스 ID와 이 기능이 필요한 이유(임시 테이블, 세션 상태, 캐시 재사용 또는 쓰기 후 읽기 일관성)를 함께 포함하십시오. 재시작은 필요하지 않습니다.

<div id="http-based-routing">
  ## HTTP 기반 라우팅
</div>

워크로드를 특정 레플리카에 고정하려면 [HTTPS 인터페이스](/ko/concepts/features/interfaces/http)를 통해 `X-ClickHouse-Replica-Tag` 헤더를 전송하십시오. 프록시는 헤더 값에 일관된 해싱을 적용하므로 레플리카 수가 변하지 않는 한 동일한 값을 사용하는 요청은 같은 레플리카로 전송됩니다. 다른 값은 독립적으로 해싱되며 같은 레플리카 또는 다른 레플리카에 할당될 수 있지만, 값이 *어느* 레플리카에 매핑될지는 선택할 수 없습니다.

기존 서비스 호스트명을 사용하십시오. 별도의 sticky 호스트명이나 DNS 변경은 필요하지 않습니다. 헤더 값에는 애플리케이션 이름, 사용자 ID 또는 워크로드 레이블 등 원하는 문자열을 사용할 수 있습니다. 헤더가 없는 요청에는 일반적인 부하 분산이 적용됩니다.

각 요청에 `X-ClickHouse-Replica-Tag` 헤더를 설정하십시오:

```bash theme={null}
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` 연결 옵션](/ko/integrations/language-clients/go/configuration#connection-settings)을 통해 헤더를 전달하십시오.

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

<div id="read-after-write-consistency">
  ### 쓰기 후 읽기 일관성
</div>

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

모든 레플리카에 걸쳐 더 강력한 일관성을 보장하려면 ClickHouse Cloud에서 [`select_sequential_consistency`](/ko/reference/settings/session-settings#select_sequential_consistency)를 `1`로 설정할 수도 있습니다.

<div id="check-which-replica">
  ### 연결된 레플리카 확인
</div>

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

<div id="limitations-of-replica-aware-routing">
  ## Replica-aware 라우팅의 한계
</div>

<div id="replica-aware-routing-does-not-guarantee-isolation">
  ### 레플리카 수가 변경되면 고정 연결도 변경됩니다
</div>

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

<div id="not-workload-isolation">
  ### Replica-aware 라우팅은 워크로드 격리가 아닙니다
</div>

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

<div id="private-networking">
  ### 프라이빗 네트워킹
</div>

HTTP 기반 라우팅은 일반 서비스 호스트명에서 [프라이빗 네트워킹](/ko/products/cloud/guides/security/connectivity/private-networking)과 함께 작동합니다. 추가 DNS 항목은 필요하지 않습니다.

<div id="replica-aware-routing-requires-http">
  ### Replica-aware 라우팅에는 HTTP 프로토콜이 필요합니다
</div>

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

<div id="troubleshooting">
  ## 문제 해결
</div>

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

* 모든 요청에 `X-ClickHouse-Replica-Tag` 헤더가 포함되어 있는지 확인하세요.
* 모든 요청에서 정확히 동일한 라우팅 값을 사용하는지 확인하세요.
* 활성화 후 잠시 기다리세요. 적용되기까지 1분 이내가 걸릴 수 있습니다.
* 최근 레플리카 수가 변경되었는지 확인하세요. 스케일링 후에는 리매핑이 발생할 수 있습니다. `SELECT hostName()`을 사용하여 새 매핑을 확인하세요.