> ## 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.

# ClickHouse에 연결

> 공용 또는 비공개 로드 밸런서나 비공개 엔드포인트(PrivateLink, Private Service Connect, Private Link)를 통해 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 서비스에 연결하는 여러 방법을 설명합니다. 보안 및 네트워킹 요구 사항에 따라 퍼블릭 로드 밸런서, 프라이빗 로드 밸런서 또는 프라이빗 엔드포인트(AWS PrivateLink, GCP Private Service Connect 또는 Azure Private Link) 중에서 선택할 수 있습니다.

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

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

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

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

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

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

<Image img="https://mintcdn.com/private-7c7dfe99-trino-dialect/tyM7Sy7bE2MbONr4/images/cloud/reference/byoc-connect-via.png?fit=max&auto=format&n=tyM7Sy7bE2MbONr4&q=85&s=1227458693b53ccb065b5299456d5688" 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-trino-dialect/tyM7Sy7bE2MbONr4/images/cloud/reference/byoc-connect-1.webp?fit=max&auto=format&n=tyM7Sy7bE2MbONr4&q=85&s=9665ffe4f2e57490686af8bd5f5c68e9" 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
```

`aws` 세그먼트는 클라우드 제공업체를 나타냅니다. 해당 클라우드에 배포하는 경우 `gcp` 또는 `azure`가 됩니다.

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

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

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

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

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

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

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

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

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

1. ClickHouse Cloud 콘솔에서 BYOC 인프라에 대해 **프라이빗 로드 밸런서 활성화**(아직 활성화되지 않은 경우)를 수행하십시오. 자세한 내용은 [Load Balancers](/ko/products/bring-your-own-cloud/configuration/configurations#load-balancers)를 참조하십시오.
2. **네트워크 연결 확인**:
   * VPC/VNet peering의 경우: peering 설정을 완료하십시오([Private Networking Setup](/ko/products/bring-your-own-cloud/onboarding/network) 참조).
   * 기타 프라이빗 네트워크의 경우: BYOC VPC/VNet에 연결할 수 있도록 라우팅이 구성되어 있는지 확인하십시오.
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 액세스 목록 문서](/ko/products/cloud/guides/security/connectivity/setting-ip-filters)를 참조하십시오.

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

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

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

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

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

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

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

<div id="connecting-via-privatelink">
  ### 프라이빗 엔드포인트를 통한 연결
</div>

PrivateLink, Private Service Connect 또는 Private Link 설정을 완료하십시오([Private Networking Setup](/ko/products/bring-your-own-cloud/onboarding/network) 참조). 설정이 완료되면 전용 프라이빗 엔드포인트 호스트명을 사용하여 ClickHouse 서비스에 연결할 수 있습니다. DNS 동작은 공급자에 따라 다릅니다. AWS에서는 엔드포인트에서 **Private DNS names**를 활성화하면 VPC 내 DNS 해석이 자동으로 해당 엔드포인트를 통해 트래픽을 라우팅합니다. GCP Private Service Connect에서는 와일드카드 DNS 레코드를 직접 생성해야 합니다. 자세한 내용은 [GCP 설정 가이드](/ko/products/bring-your-own-cloud/onboarding/network-gcp)를 참조하십시오. 마찬가지로 Azure Private Link에서는 VNet에 연결된 와일드카드 레코드가 포함된 Private DNS 존이 필요합니다. 자세한 내용은 [Azure 설정 가이드](/ko/products/bring-your-own-cloud/onboarding/network-azure)를 참조하십시오.

프라이빗 엔드포인트 호스트명은 퍼블릭 엔드포인트와 유사하지만, 서비스 하위 도메인과 BYOC infrastructure 하위 도메인 사이에 클라우드별 레이블이 추가됩니다. AWS에서는 `vpce`, GCP에서는 `p`, Azure에서는 `privatelink`가 추가됩니다. 예시:

* **퍼블릭 엔드포인트(AWS)**: `h5ju65kv87.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`
* **PrivateLink 엔드포인트(AWS)**: `h5ju65kv87.vpce.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`
* **Private Service Connect 엔드포인트(GCP)**: `h5ju65kv87.p.mhp0y4dmph.us-central1.gcp.clickhouse-byoc.com`
* **Private Link 엔드포인트(Azure)**: `h5ju65kv87.privatelink.mhp0y4dmph.westus3.azure.clickhouse-byoc.com`

엔드포인트를 설정하고 허용 목록에 추가한 후 **Connect** 대화 상자의 **Connection via** 드롭다운에서 **PrivateLink**(GCP에서는 **Private Service Connect**, Azure에서는 **Private Link**)를 선택하면 프라이빗 엔드포인트 연결 정보를 바로 복사할 수 있습니다.

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

PrivateLink, Private Service Connect 또는 Private Link를 사용하려면 각 ClickHouse 서비스에서 클라이언트 연결의 Endpoint ID를 명시적으로 허용해야 합니다. ClickHouse Cloud 콘솔에서 허용 목록을 직접 관리할 수 있습니다. 서비스의 설정 페이지를 열고 **Set up private endpoint**를 클릭한 후 클라우드 제공업체의 엔드포인트 식별자를 입력하십시오.

* **AWS**: VPC 엔드포인트 ID([AWS 설정 가이드](/ko/products/bring-your-own-cloud/onboarding/network-aws#setup-privatelink) 참조)
* **GCP**: PSC Connection ID([GCP 설정 가이드](/ko/products/bring-your-own-cloud/onboarding/network-gcp#setup-psc) 참조)
* **Azure**: Private Endpoint Resource ID([Azure 설정 가이드](/ko/products/bring-your-own-cloud/onboarding/network-azure#setup-privatelink) 참조)

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

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

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

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

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