Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

AWS PrivateLink

View as MarkdownEdit this pageReport an issueSet up docs MCP
Scale 플랜 기능

AWS PrivateLink Scale 및 Enterprise 플랜에서 제공됩니다. 업그레이드하려면 Cloud Console의 플랜 페이지를 방문하세요.

AWS PrivateLink를 사용하면 트래픽을 공용 인터넷에 노출하지 않고 VPC, AWS 서비스, 온프레미스 시스템, ClickHouse Cloud 간에 안전한 연결을 설정할 수 있습니다. 이 문서에서는 AWS PrivateLink를 사용해 ClickHouse Cloud에 연결하는 단계를 안내합니다.

ClickHouse Cloud 서비스에 대한 액세스를 AWS PrivateLink 주소로만 제한하려면 ClickHouse Cloud IP 액세스 목록의 안내를 따르십시오.

ClickHouse Cloud는 다음 AWS 리전에 호스팅된 서비스에 대해 교차 리전 PrivateLink를 지원합니다.

이 표에는 서비스 호스팅 리전만 포함됩니다. 소비자 인터페이스 VPC 엔드포인트 리전에는 별도의 허용 목록이 적용됩니다. 예를 들어 mx-central-1은 해당 리전에 호스팅된 서비스에서는 교차 리전 액세스를 활성화할 수 없지만 허용된 소비자 리전입니다.

리전 코드 리전 이름
af-south-1 아프리카(케이프타운)
ap-east-1 아시아 태평양(홍콩)
ap-northeast-1 아시아 태평양(도쿄)
ap-northeast-2 아시아 태평양(서울)
ap-south-1 아시아 태평양(뭄바이)
ap-southeast-1 아시아 태평양(싱가포르)
ap-southeast-2 아시아 태평양(시드니)
ap-southeast-3 아시아 태평양(자카르타)
ap-southeast-5 아시아 태평양(말레이시아)
ca-central-1 캐나다(중부)
eu-central-1 유럽(프랑크푸르트)
eu-north-1 유럽(스톡홀름)
eu-west-1 유럽(아일랜드)
eu-west-2 유럽(런던)
il-central-1 이스라엘(텔아비브)
me-central-1 중동(UAE)
sa-east-1 남아메리카(상파울루)
us-east-1 미국 동부(북부 버지니아)
us-east-2 미국 동부(오하이오)
us-west-2 미국 서부(오리건)

AWS PrivateLink를 활성화하려면 다음 작업을 완료하십시오:

  1. 엔드포인트 "Service name"을 확인합니다.
  2. AWS 엔드포인트를 생성합니다.
  3. "Endpoint ID"를 ClickHouse Cloud 조직에 추가합니다.
  4. "Endpoint ID"를 ClickHouse 서비스 허용 목록에 추가합니다.

Terraform 예시는 여기에서 확인할 수 있습니다.

중요한 고려 사항

ClickHouse는 AWS 리전 내에서 동일한 게시된 서비스 엔드포인트를 재사용할 수 있도록 서비스를 그룹으로 묶으려고 합니다. 그러나 이러한 그룹화가 항상 보장되는 것은 아니며, 특히 서비스를 여러 ClickHouse 조직에 분산해 둔 경우에는 더욱 그렇습니다. 이미 ClickHouse 조직의 다른 서비스에 대해 PrivateLink를 구성한 경우에는 이러한 그룹화 덕분에 대부분의 단계를 건너뛰고 마지막 단계인 ClickHouse 서비스 허용 목록에 ClickHouse "Endpoint ID"를 추가하는 단계로 바로 진행할 수 있는 경우가 많습니다.

이 절차의 사전 요구 사항

시작하기 전에 다음이 필요합니다:

  1. AWS 계정.
  2. ClickHouse 측에서 Private Endpoint를 생성하고 관리하는 데 필요한 권한이 포함된 ClickHouse API Key.

단계

AWS PrivateLink를 통해 ClickHouse Cloud 서비스를 연결하려면 다음 단계를 따르십시오.

endpoint "Service name" 확인하기

옵션 1: ClickHouse Cloud 콘솔

ClickHouse Cloud 콘솔에서 PrivateLink를 통해 연결할 서비스를 연 다음, 설정 메뉴로 이동합니다.

Private Endpoints

Service name과 DNS name을 메모한 다음, 다음 단계로 이동하세요.

옵션 2: API

먼저, 명령을 실행하기 전에 다음 환경 변수를 설정하십시오.

REGION=<Your region code using the AWS format, for example: us-west-2>
PROVIDER=aws
KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
SERVICE_NAME=<Your ClickHouse service name>

리전, 공급자, 서비스 이름으로 필터링하여 ClickHouse INSTANCE_ID를 확인합니다:

INSTANCE_ID=$(curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services" | \
jq ".result[] | select (.region==\"${REGION:?}\" and .provider==\"${PROVIDER:?}\" and .name==\"${SERVICE_NAME:?}\") | .id " -r)

PrivateLink 구성에 사용할 endpointServiceId 및 privateDnsHostname을 확인하세요:

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | \
jq .result

이 명령을 실행하면 다음과 비슷한 결과가 반환됩니다:

{
  "endpointServiceId": "com.amazonaws.vpce.us-west-2.vpce-svc-xxxxxxxxxxxxxxxxx",
  "privateDnsHostname": "xxxxxxxxxx.us-west-2.vpce.aws.clickhouse.cloud"
}

endpointServiceId와 privateDnsHostname를 메모해 두고 다음 단계로 진행하세요.

AWS 엔드포인트 생성

옵션 1: AWS 콘솔

AWS 콘솔을 열고 VPC → Endpoints → Create endpoints로 이동하세요.

Endpoint services that use NLBs and GWLBs를 선택한 다음, Service Name 필드에 엔드포인트 "Service name" 확인 단계에서 얻은 Service nameconsole 또는 endpointServiceIdAPI를 입력하세요. Verify service를 클릭하세요.

AWS PrivateLink 엔드포인트 설정

"Service name couldn't be verified." 오류가 발생하면 지원되는 리전 목록에 새 리전을 추가하도록 고객 지원팀에 문의하십시오.

다음으로, VPC와 서브넷을 선택하세요.

VPC 및 서브넷 선택

선택 사항으로 Security Group/태그를 할당하세요.

VPC 엔드포인트를 생성한 후 Endpoint ID 값을 기록해 두세요. 다음 단계에서 필요합니다.

VPC 엔드포인트 ID

옵션 2: AWS CloudFormation

다음으로, 엔드포인트 "Service name" 확인 단계에서 확인한 Service nameconsole 또는 endpointServiceIdAPI를 사용해 VPC 엔드포인트를 생성해야 합니다. 서브넷 ID, 보안 그룹, VPC ID를 올바르게 사용해야 합니다.

Resources:
  ClickHouseInterfaceEndpoint:
    Type: 'AWS::EC2::VPCEndpoint'
    Properties:
      VpcEndpointType: Interface
      PrivateDnsEnabled: false
      ServiceName: <Service name(endpointServiceId), pls see above>
      VpcId: vpc-vpc_id
      SubnetIds:
        - subnet-subnet_id1
        - subnet-subnet_id2
        - subnet-subnet_id3
      SecurityGroupIds:
        - sg-security_group_id1
        - sg-security_group_id2
        - sg-security_group_id3

VPC 엔드포인트를 생성한 후 Endpoint ID 값을 기록해 두세요. 다음 단계에서 필요합니다.

옵션 3: Terraform

아래의 service_name은 Endpoint "Service name" 가져오기 단계에서 확인한 Service name콘솔 또는 endpointServiceIdAPI입니다

resource "aws_vpc_endpoint" "this" {
  vpc_id            = var.vpc_id
  service_name      = "<pls see comment above>"
  vpc_endpoint_type = "Interface"
  security_group_ids = [
    Var.security_group_id1,var.security_group_id2, var.security_group_id3,
  ]
  subnet_ids          = [var.subnet_id1,var.subnet_id2,var.subnet_id3]
  private_dns_enabled = false
  service_region      = "(Optional) If specified, the VPC endpoint will connect to the service in the provided region. Define it for multi-regional PrivateLink connections."
}

VPC 엔드포인트를 생성한 후 Endpoint ID 값을 메모해 두세요. 다음 단계에서 필요합니다.

엔드포인트의 프라이빗 DNS 이름 설정

Endpoint "Service name" 가져오기 단계에서 얻은 "DNS name"이 AWS Endpoint 네트워크 인터페이스를 가리키도록 설정해야 합니다. 이렇게 하면 VPC/네트워크 내의 서비스와 구성 요소가 이를 올바르게 해석할 수 있습니다.

ClickHouse 서비스의 허용 목록에 "Endpoint ID" 추가

옵션 1: ClickHouse Cloud 콘솔

추가하려면 ClickHouse Cloud 콘솔로 이동하여 PrivateLink를 통해 연결할 서비스를 연 다음 설정으로 이동하십시오. Private Endpoint 설정을 클릭하여 private endpoints 설정을 여십시오. AWS Endpoint 생성 단계에서 얻은 Endpoint ID를 입력하십시오. "엔드포인트 생성"을 클릭하십시오.

Private Endpoints 필터

제거하려면 ClickHouse Cloud 콘솔로 이동하여 서비스를 찾은 다음, 해당 서비스의 설정으로 이동하고 제거할 엔드포인트를 찾으십시오. 엔드포인트 목록에서 제거하십시오.

옵션 2: API

PrivateLink를 통해 사용할 각 인스턴스의 허용 목록에 Endpoint ID를 추가해야 합니다.

Create AWS Endpoint 단계의 정보를 사용해 ENDPOINT_ID 환경 변수를 설정합니다.

명령을 실행하기 전에 다음 환경 변수를 설정합니다:

REGION=<AWS 형식의 리전 코드, 예: us-west-2>
PROVIDER=aws
KEY_ID=<ClickHouse 키 ID>
KEY_SECRET=<ClickHouse 키 시크릿>
ORG_ID=<ClickHouse 조직 ID>
SERVICE_NAME=<ClickHouse 서비스 이름>

허용 목록에 Endpoint ID를 추가하려면:

cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "add": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
-X PATCH -H "Content-Type: application/json" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" \
-d @pl_config.json | jq

허용 목록에서 Endpoint ID를 제거하려면:

cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "remove": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
-X PATCH -H "Content-Type: application/json" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" \
-d @pl_config.json | jq

Private Link가 활성화된 각 서비스에는 공용 엔드포인트와 Private Endpoint가 있습니다. Private Link를 사용해 연결하려면 엔드포인트 "Service name" 가져오기에서 확인한 privateDnsHostnameAPI 또는 DNS Name콘솔의 Private Endpoint를 사용해야 합니다.

프라이빗 DNS 호스트명 확인

옵션 1: ClickHouse Cloud 콘솔

ClickHouse Cloud 콘솔에서 설정으로 이동합니다. Set up private endpoint 버튼을 클릭합니다. 열리는 플라이아웃에서 DNS Name을 복사합니다.

Private Endpoint DNS 이름
옵션 2: API

명령을 실행하기 전에 다음 환경 변수를 설정하세요:

KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
INSTANCE_ID=<Your ClickHouse service name>

INSTANCE_ID는 이 단계에서 확인할 수 있습니다.

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | \
jq .result

다음과 비슷한 내용이 출력됩니다:

{
  "endpointServiceId": "com.amazonaws.vpce.us-west-2.vpce-svc-xxxxxxxxxxxxxxxxx",
  "privateDnsHostname": "xxxxxxxxxx.us-west-2.vpce.aws.clickhouse.cloud"
}

이 예시에서는 privateDnsHostname 호스트명 값으로 연결하면 PrivateLink로 라우팅되지만, endpointServiceId 호스트명으로 연결하면 인터넷을 통해 라우팅됩니다.

문제 해결

하나의 리전에 여러 PrivateLink

대부분의 경우 각 VPC에 대해 엔드포인트 서비스를 하나만 생성하면 됩니다. 이 엔드포인트는 VPC에서 여러 ClickHouse Cloud 서비스로 요청을 라우팅할 수 있습니다. 여기를 참조하십시오.

Private Endpoint 연결 시간 초과
  • VPC 엔드포인트에 Security Group을 연결하십시오.
  • 엔드포인트에 연결된 Security Group의 inbound 규칙을 확인하고 ClickHouse 포트를 허용하십시오.
  • 연결 테스트에 사용되는 VM에 연결된 Security Group의 outbound 규칙을 확인하고 ClickHouse 포트에 대한 연결을 허용하십시오.
Private Hostname: 호스트 주소를 찾을 수 없음
  • DNS 구성을 확인하십시오.
피어에 의해 연결 재설정
  • 엔드포인트 ID가 서비스 허용 목록에 추가되지 않았을 가능성이 높습니다. 단계를 확인하십시오.
엔드포인트 필터 확인

명령어를 실행하기 전에 다음 환경 변수를 설정하십시오.

KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<please set ClickHouse organization ID>
INSTANCE_ID=<Instance ID>

INSTANCE_ID는 단계에서 가져올 수 있습니다.

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
-X GET -H "Content-Type: application/json" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" | \
jq .result.privateEndpointIds
원격 데이터베이스에 연결하기

AWS PrivateLink documentation에 따르면 다음과 같습니다.

하나 이상의 소비자 VPC에서 서비스 제공자 VPC의 특정 서비스 또는 인스턴스 집합에 단방향으로 액세스할 수 있도록 하려는 클라이언트/서버 구성인 경우 AWS PrivateLink를 사용하십시오. 연결은 소비자 VPC의 클라이언트만 서비스 제공자 VPC의 서비스로 시작할 수 있습니다.

ClickHouse Cloud에서 MySQL 또는 PostgreSQL 테이블 함수를 AWS VPC에 호스팅된 데이터베이스에 연결하려면, ClickHouse Cloud로부터의 연결을 허용하도록 AWS Security Group을 구성하십시오. ClickHouse Cloud 리전의 기본 egress IP 주소와 사용 가능한 고정 IP 주소도 함께 확인하십시오.

Navigation