ClickPipes용 GCP Private Service Connect

GCP Private Service Connect (PSC)를 사용하여 ClickPipes와 GCP에서 호스팅되는 데이터 소스 간에 보안 연결을 설정할 수 있습니다. ClickPipes는 자체 VPC에 **역방향 Private Endpoint(RPE)**를 생성하고 데이터 소스용으로 게시된 endpoint service를 가리키도록 구성하므로, 트래픽이 공용 인터넷에 노출되지 않습니다.

ClickPipes는 글로벌 액세스를 통해 cross-region PSC 연결을 지원합니다. ClickPipes 인프라가 실행되는 리전과 다른 리전에 있는 엔드포인트에는 글로벌 액세스가 필요합니다. 자세한 내용은 ClickPipes GCP 리전 문서를 확인하십시오.

지원되는 패턴

패턴	적용되는 경우	서비스 어태치먼트
네이티브 PSC	Google Cloud SQL, AlloyDB, Google Cloud Managed Service for Apache Kafka 등 PSC 서비스 어태치먼트를 자동으로 게시하는 관리형 서비스	인스턴스에서 PSC를 활성화하면 자동으로 생성됩니다.
프로듀서 소유 PSC	Compute Engine의 Postgres 또는 private IP로만 연결할 수 있는 관리형 서비스처럼 서비스 어태치먼트를 게시하지 않는 데이터 소스	사용자가 생성하고 관리합니다.

사전 요구 사항

GCP에서 호스팅되는 ClickHouse Cloud 서비스. ClickPipes는 몇 가지 예외를 제외하고 ClickHouse Cloud 서비스와 동일한 리전에서 실행됩니다.
소스에서 PSC를 활성화하고 PSC 서비스 어태치먼트를 관리할 수 있는 IAM 권한(roles/compute.networkAdmin).
서비스 어태치먼트에 연결하도록 허용된 ClickPipes 소비자 프로젝트(clickpipes-production).
ClickPipes를 프로그래밍 방식으로 프로비저닝하는 경우: 서비스를 소유한 조직의 ClickHouse Cloud API Key.

역방향 프라이빗 엔드포인트 생성하기

RPE를 생성하려면 데이터 소스에 대한 다음 정보가 필요합니다.

서비스 어태치먼트 URI: projects/<PROJECT>/regions/<REGION>/serviceAttachments/<NAME>, 데이터 소스 앞에 게시된 PSC 엔드포인트입니다.
Private DNS 이름: 파이프가 연결할 호스트명입니다. PSC 엔드포인트에는 DNS 이름이 연결되지 않은 고정 내부 IP가 할당되므로, ClickPipes가 이 호스트명을 해당 IP로 확인합니다.

ClickPipes UI
Terraform
API

ClickHouse Cloud에서 서비스를 열고 Data Sources > ClickPipes로 이동합니다.
수집할 데이터 소스를 선택합니다.
Setup your ClickPipe connection에서 Use secure connection을 켠 다음 + Reverse private endpoint를 클릭하고 GCP PSC service attachment를 선택합니다.
Service attachment URI, Private DNS name, Description을 입력합니다.
Create를 클릭합니다. 엔드포인트 상태가 Provisioning에서 Ready로 변경됩니다. (네이티브 PSC는 자동으로 승인되므로 PendingAcceptance는 표시되지 않습니다.)

사용자 지정 Private DNS 매핑은 clickhouse_clickpipes_reverse_private_endpoint의 속성이 아닙니다. 전체 매핑 목록을 대체하는 방식으로 설정되며, ID로 엔드포인트를 참조하는 별도의 clickhouse_clickpipes_reverse_private_endpoint_custom_private_dns 리소스에서 관리합니다.

resource "clickhouse_clickpipes_reverse_private_endpoint" "gcp_psc" {
  service_id             = var.clickhouse_service_id
  description            = "GCP PSC endpoint"
  type                   = "GCP_PSC_SERVICE_ATTACHMENT"
  gcp_service_attachment = "projects/<PROJECT>/regions/<REGION>/serviceAttachments/<NAME>"
}

resource "clickhouse_clickpipes_reverse_private_endpoint_custom_private_dns" "gcp_psc" {
  service_id                  = var.clickhouse_service_id
  reverse_private_endpoint_id = clickhouse_clickpipes_reverse_private_endpoint.gcp_psc.id

  mapping = [
    { private_dns_name = "<PRIVATE_DNS_NAME>" }
  ]
}

curl --silent --user $KEY_ID:$KEY_SECRET \
  -X POST -H "Content-Type: application/json" \
  https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickpipesReversePrivateEndpoints \
  -d '{
    "type": "GCP_PSC_SERVICE_ATTACHMENT",
    "description": "GCP PSC endpoint",
    "gcpServiceAttachment": "projects/<PROJECT>/regions/<REGION>/serviceAttachments/<NAME>",
    "customPrivateDnsMappings": [
      { "privateDnsName": "<PRIVATE_DNS_NAME>" }
    ]
  }'

사용자 지정 Private DNS 이름

GCP PSC는 DNS를 전파하지 않으므로 ClickPipes가 이를 엔드포인트의 고정 내부 IP로 확인할 수 있도록 모든 GCP PSC 엔드포인트에 사용자 지정 Private DNS 매핑이 필요합니다. 표준 ClickPipes 사용자 지정 Private DNS 명명 규칙이 적용됩니다. 와일드카드 지원, 서비스의 역방향 프라이빗 엔드포인트 전체에서의 고유성, 예약된 접미사 제한은 모든 provider에서 동일하게 적용됩니다. 와일드카드는 특히 유용합니다. 예를 들어 *.<cluster>.<region>.managedkafka.<project>.cloud.goog와 같은 단일 매핑으로 관리형 Kafka 클러스터의 모든 broker를 처리할 수 있습니다. GCP PSC에서는 매핑의 privateDnsName만 사용됩니다. PSC 엔드포인트는 연결할 DNS 이름 없이 고정 IP를 노출하므로 internalDNSName 필드는 지원되지 않습니다. 매핑은 항상 해당 IP로 확인됩니다.

프로듀서 소유 연결 승인

프로듀서 소유 PSC에서는 연결이 자동으로 수락되도록 ClickPipes 소비자 프로젝트(clickpipes-production)를 서비스 어태치먼트의 자동 수락 목록에 추가하십시오. 이 작업을 건너뛰면 수동으로 승인할 때까지 RPE가 PendingAcceptance 상태로 남아 있습니다. 연결을 수락하려면 서비스 어태치먼트의 소비자 수락 목록에 엔드포인트의 숫자 ID 기반 URI(projects/<PROJECT>/regions/<REGION>/forwardingRules/<NUMERIC_ID>)를 추가해야 합니다. 서비스 어태치먼트에서 대기 중인 연결의 endpointWithId 값을 가져오려면 다음을 실행하십시오.

gcloud beta compute service-attachments describe <SERVICE_ATTACHMENT_NAME> \
  --region=<REGION> --project=<YOUR_PROJECT_ID> \
  --format='json(connectedEndpoints)'

status가 PENDING인 항목의 endpointWithId에서 https://www.googleapis.com/compute/beta/ 접두사를 제거하고, 결과를 --consumer-accept-list에 전달합니다:

--consumer-accept-list는 새 소비자 프로젝트를 추가하는 대신 허용 목록 전체를 덮어씁니다. 서비스 어태치먼트가 이미 다른 프로젝트나 엔드포인트를 허용하는 경우, 모두 같은 명령에 전달해야 합니다. 그렇지 않으면 누락한 항목의 액세스 권한이 사라집니다.

gcloud beta compute service-attachments update <SERVICE_ATTACHMENT_NAME> \
  --region=<REGION> --project=<YOUR_PROJECT_ID> \
  --consumer-accept-list=projects/<PROJECT>/regions/<REGION>/forwardingRules/<NUMERIC_ID> \
  --reconcile-connections

여기에서는 ClickPipes API/Terraform 응답의 endpoint_id를 사용하지 마십시오. 이 값은 GCP에서 요구하는 숫자 ID가 아니라 전달 규칙의 이름이므로 허용 목록과 일치하지 않습니다. 반드시 서비스 어태치먼트의 pending 상태인 endpointWithId에서 숫자 ID를 가져오십시오.

역방향 프라이빗 엔드포인트 관리

ClickHouse Cloud 서비스 설정에서 기존 역방향 프라이빗 엔드포인트를 관리할 수 있습니다.

ClickHouse Cloud 콘솔 사이드바에서 Settings로 이동합니다.

ClickPipe reverse private endpoints 아래에서 Reverse private endpoints를 클릭합니다. 플라이아웃에 역방향 프라이빗 엔드포인트의 상세 정보가 표시됩니다. 여기에서 RPE를 삭제할 수 있습니다. 엔드포인트의 ×를 클릭하고 삭제를 확인하십시오. 삭제는 영구적이며 현재 해당 엔드포인트를 사용하는 모든 ClickPipe가 작동하지 않게 됩니다. 엔드포인트의 사용자 지정 Private DNS 매핑을 변경하려면 Cloud API 또는 Terraform을 사용하십시오. 업데이트하면 매핑이 추가되는 것이 아니라 전체 매핑 목록이 대체됩니다. 엔드포인트에 Rejected 또는 Failed가 표시되면 상태 아래의 메시지를 확인하십시오. 이 메시지는 프로듀서가 거부한 연결인지, 종료되었거나 조치가 필요한 연결인지를 구분해 줍니다. 두 상태 모두 일반적으로 서비스 어태치먼트의 허용 목록에 ClickPipes 소비자 프로젝트가 포함되지 않았음을 의미합니다. GCP가 엔드포인트에 대해 보고하는 상태를 확인하려면 서비스 어태치먼트의 connectedEndpoints를 설명하십시오.

알려진 제한 사항

PSC 서비스 어태치먼트는 한 번에 하나의 ClickHouse Cloud 서비스에서만 클레임할 수 있으며, 여러 서비스에서 재사용할 수 없습니다. 서비스 어태치먼트를 다른 서비스로 이전하려면 ClickHouse 지원팀에 문의하여 기존 클레임을 해제하십시오.

ClickPipes for Streaming

ClickPipes for Object Storage

ClickPipes for CDC

Programmatic access

Networking

ClickPipes용 GCP Private Service Connect

지원되는 패턴

사전 요구 사항

역방향 프라이빗 엔드포인트 생성하기

사용자 지정 Private DNS 이름

프로듀서 소유 연결 승인

역방향 프라이빗 엔드포인트 관리

알려진 제한 사항

​지원되는 패턴

​사전 요구 사항

​역방향 프라이빗 엔드포인트 생성하기

​사용자 지정 Private DNS 이름

​프로듀서 소유 연결 승인

​역방향 프라이빗 엔드포인트 관리

​알려진 제한 사항

지원되는 패턴

사전 요구 사항

역방향 프라이빗 엔드포인트 생성하기

사용자 지정 Private DNS 이름

프로듀서 소유 연결 승인

역방향 프라이빗 엔드포인트 관리

알려진 제한 사항