> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickHouse에 연결

> 공용, 비공개 또는 PrivateLink 엔드포인트를 통해 BYOC ClickHouse 서비스에 연결

export const Image = ({img, alt, size = "lg"}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} />
      </Frame>
    </div>;
};

이 페이지에서는 BYOC에서 ClickHouse 서비스에 연결하는 여러 방법을 설명합니다. 보안 및 네트워킹 요구 사항에 따라 퍼블릭 로드 밸런서, 프라이빗 로드 밸런서 또는 PrivateLink/Private Service Connect 엔드포인트 중에서 선택할 수 있습니다.

<div id="connection-via">
  ## 콘솔에서 연결 경로 선택하기
</div>

모든 BYOC 서비스의 연결 세부 정보는 ClickHouse Cloud 콘솔에서 확인할 수 있습니다. 서비스를 열고 **Connect**를 클릭하십시오.

BYOC 서비스의 **Connect** 대화상자에는 **Connection via** 드롭다운이 포함되어 있습니다. 이를 사용해 서비스에 연결하는 방식을 선택하십시오.

* **퍼블릭 로드 밸런서** — 인터넷에 노출된 엔드포인트입니다.
* **프라이빗 로드 밸런서** — VPC peering 또는 연결된 네트워크를 통해 접근하는 내부 엔드포인트입니다. 인프라에서 [프라이빗 로드 밸런서](#private-load-balancer)가 활성화된 경우에만 표시됩니다.
* **PrivateLink** (AWS) / **Private Service Connect** (GCP) — 클라우드 제공업체의 프라이빗 엔드포인트 호스트명입니다. [PrivateLink or Private Service Connect](#privatelink-or-private-service-connect)가 활성화된 경우에만 표시됩니다.

경로를 선택하면 대화상자의 모든 연결 예시에서 호스트명이 업데이트됩니다. 여기에는 HTTPS (`curl`) 명령, 네이티브 클라이언트, JDBC, MySQL, 언어별 클라이언트 스니펫(Python, Node.js, Java, Go, C#)이 포함되므로, 호스트명을 수동으로 수정하지 않고도 필요한 정확한 경로에 맞는 바로 사용 가능한 명령을 복사할 수 있습니다.

드롭다운에는 인프라에서 활성화된 경로만 표시되며, 목록은 대화상자를 열 때마다 갱신됩니다. 새로 활성화된 프라이빗 로드 밸런서 또는 PrivateLink 엔드포인트는 **Connect**를 다음에 열면 전파 지연 없이 바로 표시됩니다. 사용할 수 있는 경로가 하나뿐이면 해당 엔드포인트가 선택된 상태로 드롭다운이 비활성화되어 표시됩니다.

<Image img="https://mintcdn.com/private-7c7dfe99/nS3fqaRk31wnsutS/images/cloud/reference/byoc-connect-via.png?fit=max&auto=format&n=nS3fqaRk31wnsutS&q=85&s=4028c9ccc734cae0794b4a62a7fddf4f" size="lg" alt="Connection via 드롭다운이 펼쳐진 Connect 대화상자. 퍼블릭 로드 밸런서, 프라이빗 로드 밸런서, PrivateLink 경로가 표시되어 있습니다." background="black" width="1500" height="1060" data-path="images/cloud/reference/byoc-connect-via.png" />

<div id="public-load-balancer">
  ## Public Load Balancer
</div>

퍼블릭 로드 밸런서는 인터넷에서 ClickHouse 서비스에 접근할 수 있도록 합니다. 이는 ClickHouse가 관리하는 전용 VPC를 사용할 때의 기본 구성입니다.

<div id="public-load-balancer-overview">
  ### 개요
</div>

* **액세스**: 공용 인터넷을 통해 액세스할 수 있습니다
* **사용 사례**: 다양한 위치나 네트워크에서 연결해야 하는 애플리케이션 및 사용자에게 적합합니다
* **보안**: TLS 암호화와 IP 필터링으로 보호됩니다(권장)

<div id="connecting-via-public-load-balancer">
  ### Public Load Balancer를 통해 연결하기
</div>

퍼블릭 엔드포인트를 사용해 ClickHouse 서비스에 연결하려면 다음 단계를 수행하세요.

1. ClickHouse Cloud 콘솔에서 **서비스 엔드포인트**를 확인하세요. 엔드포인트는 서비스의 "Connect" 섹션에 표시됩니다.

<Image img="https://mintcdn.com/private-7c7dfe99/REHSqgCLT_igIuJP/images/cloud/reference/byoc-connect-1.webp?fit=max&auto=format&n=REHSqgCLT_igIuJP&q=85&s=869486bfed0c8ee1b9028e7a08948d91" size="lg" alt="BYOC 연결" background="black" width="2466" height="1742" data-path="images/cloud/reference/byoc-connect-1.webp" />

예시:

```text theme={null}
sb9jmrq2ne.asf3kcggao.ap-southeast-1.aws.clickhouse-byoc.com
```

<div id="public-ip-filtering">
  ### IP 필터링
</div>

공용 로드 밸런서를 사용하는 경우, 허용된 IP 주소 또는 CIDR 대역으로만 액세스를 제한할 수 있도록 IP 필터링(IP 액세스 목록)을 사용하는 것을 **강력히 권장합니다**.

IP 필터링에 대한 자세한 내용은 [IP 액세스 목록 문서](/docs/ko/products/cloud/guides/security/connectivity/setting-ip-filters)를 참조하십시오.

<div id="private-load-balancer">
  ## 프라이빗 로드 밸런서
</div>

프라이빗 로드 밸런서는 연결된 네트워크(예: 피어링된 VPC) 내부에서만 접근할 수 있도록 ClickHouse 서비스에 대한 내부 액세스를 제공합니다. 이는 고객 관리형 VPC를 사용할 때의 기본 구성입니다.

<div id="public-load-balancer-overview">
  ### 개요
</div>

* **액세스**: 프라이빗 네트워크 인프라 내부에서만 접근할 수 있습니다
* **사용 사례**: 동일한 클라우드 환경에서 실행되거나 VPC peering으로 연결된 애플리케이션에 적합합니다
* **보안**: 트래픽이 프라이빗 네트워크 내부에서만 오가므로 공용 인터넷에는 노출되지 않습니다

<div id="connecting-via-private-load-balancer">
  ### Private Load Balancer를 통해 연결하기
</div>

프라이빗 엔드포인트를 사용해 연결하려면 다음 단계를 수행하십시오.

1. **프라이빗 로드 밸런서 활성화**(아직 활성화되지 않은 경우). 배포에 [프라이빗 로드 밸런서 활성화](/docs/ko/products/bring-your-own-cloud/configuration/configurations#load-balancers)가 필요하면 ClickHouse 지원팀에 문의하십시오.
2. **네트워크 연결 확인**:
   * VPC peering의 경우: VPC peering 설정을 완료하십시오([Private Networking Setup](/docs/ko/products/bring-your-own-cloud/onboarding/network) 참조).
   * 기타 프라이빗 네트워크의 경우: BYOC VPC에 연결할 수 있도록 라우팅이 구성되어 있는지 확인하십시오.
3. **프라이빗 엔드포인트 확인**:
   프라이빗 엔드포인트는 ClickHouse Cloud 콘솔에서 해당 서비스의 "Connect" 섹션에서 확인할 수 있습니다. 프라이빗 엔드포인트는 퍼블릭 엔드포인트와 동일한 형식을 따르지만, 서비스 ID 부분에 `-private` 접미사가 추가됩니다. 예시는 다음과 같습니다.

   * **퍼블릭 엔드포인트**: `sb9jmrq2ne.asf3kcggao.ap-southeast-1.aws.clickhouse-byoc.com`
   * **프라이빗 엔드포인트**: `sb9jmrq2ne-private.asf3kcggao.ap-southeast-1.aws.clickhouse-byoc.com`

   `-private` 호스트명을 직접 만들기보다는 **Connect** 대화상자의 **Connection via** 드롭다운에서 **Private load balancer**를 선택해 엔드포인트와 미리 준비된 연결 명령을 바로 복사하십시오.

<div id="public-ip-filtering">
  ### IP 필터링
</div>

프라이빗 로드 밸런서는 내부 네트워크에서만 접근할 수 있도록 제한되지만, 프라이빗 네트워크 내에서 어떤 연결 원본이 접속할 수 있는지 더 세밀하게 제어하기 위해 IP 필터링을 추가로 설정할 수 있습니다. 프라이빗 로드 밸런서의 IP 필터링은 퍼블릭 로드 밸런서와 동일한 구성 방식을 사용합니다. 즉, 허용할 IP 주소 또는 CIDR 범위를 정의하면 ClickHouse Cloud가 이러한 규칙을 각 엔드포인트 유형에 맞게 적용합니다. 플랫폼은 퍼블릭 CIDR 범위와 프라이빗 CIDR 범위를 자동으로 구분하여 해당 로드 밸런서 엔드포인트에 할당합니다. 자세한 내용은 [IP 액세스 목록 문서](/docs/ko/products/cloud/guides/security/connectivity/setting-ip-filters)를 참조하십시오.

<div id="security-group-configuration">
  ### Security Group 구성
</div>

AWS 배포에서는 프라이빗 로드 밸런서의 보안 그룹이 엔드포인트에 액세스할 수 있는 네트워크를 제어합니다. 기본적으로는 BYOC VPC 내부의 트래픽만 허용됩니다.

자세한 내용은 [프라이빗 로드 밸런서 보안 그룹 구성](/docs/ko/products/bring-your-own-cloud/configuration/configurations#private-load-balancer-security-group)을 참조하십시오.

<div id="privatelink-or-private-service-connect">
  ## PrivateLink 또는 Private Service Connect
</div>

AWS PrivateLink와 GCP Private Service Connect는 가장 안전한 연결 옵션을 제공하며, VPC peering이나 인터넷 게이트웨이 없이 ClickHouse 서비스에 비공개로 접속할 수 있도록 합니다.

<div id="public-load-balancer-overview">
  ### 개요
</div>

* **액세스**: 클라우드 제공업체의 관리형 서비스를 통한 프라이빗 연결
* **네트워크 격리**: 트래픽이 공용 인터넷을 전혀 거치지 않습니다
* **사용 사례**: 최고 수준의 보안과 네트워크 격리가 필요한 Enterprise 배포
* **이점**:
  * VPC peering이 필요하지 않음
  * 네트워크 아키텍처 단순화
  * 보안 및 컴플라이언스 수준 향상

<div id="connecting-via-privatelink">
  ### PrivateLink/Private Service Connect를 통한 연결
</div>

PrivateLink 또는 Private Service Connect 설정을 완료하십시오([Private Networking Setup](/docs/ko/products/bring-your-own-cloud/onboarding/network) 참조). 구성이 완료되면 PrivateLink 전용 endpoint 포맷을 사용해 ClickHouse 서비스에 연결할 수 있습니다. PrivateLink endpoint에는 VPC endpoint를 통해 라우팅된다는 것을 나타내는 `vpce` 하위 도메인이 포함됩니다. VPC의 DNS 해상도는 트래픽을 PrivateLink endpoint를 통해 자동으로 라우팅합니다.

PrivateLink endpoint 포맷은 퍼블릭 엔드포인트와 유사하지만, 서비스 하위 도메인과 BYOC 인프라 하위 도메인 사이에 `vpce` 하위 도메인이 포함됩니다. 예시는 다음과 같습니다.

* **퍼블릭 엔드포인트**: `h5ju65kv87.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`
* **PrivateLink endpoint**: `h5ju65kv87.vpce.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`

endpoint가 설정되고 허용 목록에 추가되면, **Connect** 대화 상자의 **Connection via** 드롭다운에서 **PrivateLink**(또는 GCP에서는 **Private Service Connect**)를 선택하여 프라이빗 엔드포인트 연결 정보를 직접 복사하십시오.

<div id="endpoint-id-allowlist">
  ### Endpoint ID 허용 목록
</div>

PrivateLink 또는 Private Service Connect를 사용하려면 클라이언트 연결의 Endpoint ID가 각 ClickHouse 서비스마다 명시적으로 허용되어 있어야 합니다. 서비스 허용 목록에 추가할 수 있도록 ClickHouse 지원팀에 문의하여 Endpoint ID를 제공하십시오.

자세한 설정 방법은 [Private Networking Setup 가이드](/docs/ko/products/bring-your-own-cloud/onboarding/network)를 참조하십시오.

<div id="choosing-connection-method">
  ## 적합한 연결 방법 선택
</div>

| 연결 방법                                   | 보안 수준            | 네트워크 요구 사항               | 사용 사례                    |
| --------------------------------------- | ---------------- | ------------------------ | ------------------------ |
| **퍼블릭 로드 밸런서**                          | 중간 (IP 필터링 사용 시) | 인터넷 접속                   | 다양한 위치의 애플리케이션/사용자       |
| **프라이빗 로드 밸런서**                         | 높음               | VPC peering 또는 프라이빗 네트워크 | 동일한 클라우드 환경 내 애플리케이션     |
| **PrivateLink/Private Service Connect** | 가장 높음            | 클라우드 제공업체 관리형 서비스        | 최대 수준의 격리가 필요한 엔터프라이즈 배포 |

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

연결 문제가 발생하는 경우:

1. **엔드포인트 접근성 확인**: 올바른 엔드포인트(퍼블릭 또는 프라이빗)를 사용하고 있는지 확인하십시오
2. **IP 필터 확인**: 퍼블릭 로드 밸런서를 사용하는 경우, IP 주소가 허용 목록에 포함되어 있는지 확인하십시오
3. **네트워크 연결 확인**: 프라이빗 연결의 경우, VPC peering 또는 PrivateLink가 올바르게 구성되어 있는지 확인하십시오
4. **보안 그룹 확인**: 프라이빗 로드 밸런서를 사용하는 경우, 보안 그룹 규칙이 소스 네트워크의 트래픽을 허용하는지 확인하십시오
5. **보안 그룹 확인**: PrivateLink 또는 Private Service Connect의 경우, Endpoint ID가 ClickHouse 서비스의 허용 목록에 추가되었는지 확인하십시오
6. **인증 검토**: 올바른 자격 증명(username 및 password)을 사용하고 있는지 확인하십시오
7. **지원 문의**: 문제가 계속되면 ClickHouse 지원팀에 문의하십시오