여기에서 비공개 프리뷰 대기자 명단에 등록할 수 있습니다.
- 활성 상태의 ClickHouse Cloud 서비스
- 수집할 Pub/Sub 토픽이 포함된 GCP 프로젝트
- 해당 프로젝트에서 서비스 계정을 생성하고 역할을 부여할 수 있는 IAM 권한
Pub/Sub용 ClickPipes는 서비스 계정 JSON 키를 사용해 GCP에 인증합니다. 파이프를 생성할 때 키 파일을 업로드하면, ClickPipes는 이를 저장 중 암호화하며 런타임에 다음 작업에 사용합니다.
- 프로젝트의 토픽을 나열하고 읽습니다.
- 메시지를 소비하기 위해 ClickPipes가 사용하는 관리형 구독을 생성하고 삭제합니다.
- 해당 subscription에서 메시지를 소비합니다.
- (선택 사항) 스키마 레지스트리에서 네이티브 Pub/Sub 스키마를 읽습니다.
현재 Workload Identity 또는 인라인 자격 증명 붙여넣기 옵션은 지원되지 않으며, 서비스 계정 JSON 키가 현재 지원되는 유일한 인증 메서드입니다.
ClickPipes를 사용하려면 토픽을 소유한 GCP 프로젝트에 다음 IAM 권한이 필요합니다. 이러한 권한은 검색(토픽 목록 조회, 검증, 샘플링), subscription 관리, 지속적인 수집, 정리까지 파이프의 전체 수명 주기를 포괄합니다.
| Permission | Purpose |
|---|
pubsub.topics.list | 검색 과정에서 프로젝트의 사용 가능한 토픽 목록을 확인합니다 |
pubsub.topics.get | 토픽이 존재하는지 확인하고 스키마 설정을 가져옵니다 |
pubsub.topics.attachSubscription | 해당 토픽에 대한 subscription을 생성할 때 필요합니다 |
subscription 수명 주기(검색 및 수집)
| Permission | Purpose |
|---|
pubsub.subscriptions.create | 관리형 subscription(clickpipes-{pipeID}) 및 임시 검색 subscription 생성 |
pubsub.subscriptions.get | 상태 점검(60초마다), 팔로워 폴링, subscription 유효성 검사 |
pubsub.subscriptions.delete | 임시 검색 subscription 정리 및 파이프 삭제 시 관리형 subscription 삭제 |
pubsub.subscriptions.consume | Receive(), Ack(), Nack(), 및 timestamp 기준 seek 작업 |
스키마 액세스(선택 사항 — 네이티브 Avro/Protobuf 토픽에만 해당)
| Permission | Purpose |
|---|
pubsub.schemas.get | Pub/Sub 스키마 레지스트리에서 네이티브 스키마 정의를 조회합니다 |
| 역할 | 충분한가? | 비고 |
|---|
roles/pubsub.editor | 예 | 필요한 모든 권한을 포함합니다. 가장 포괄적인 옵션입니다. |
roles/pubsub.subscriber | 아니요 | topics.list, topics.attachSubscription, subscriptions.create, subscriptions.delete, schemas.get 권한이 없습니다. |
roles/pubsub.viewer | 아니요 | 읽기 전용 — subscription 관리나 활용은 할 수 없습니다. |
| 사용자 지정 역할 (권장) | 예 | 최소 권한 원칙에 따라 위의 7가지 핵심 권한을 사용하십시오(schemas.get는 선택 사항). |
gcloud CLI를 사용해 수행할 수 있습니다:
gcloud iam roles create clickpipes.pubsub.ingestion \
--project=YOUR_PROJECT_ID \
--title="ClickPipes Pub/Sub Ingestion" \
--description="Permissions required by ClickHouse ClickPipes to ingest from Pub/Sub" \
--permissions=pubsub.topics.list,pubsub.topics.get,pubsub.topics.attachSubscription,pubsub.subscriptions.create,pubsub.subscriptions.get,pubsub.subscriptions.delete,pubsub.subscriptions.consume \
--stage=GA
선택적 권한네이티브 Pub/Sub Avro 또는 Protobuf 스키마를 사용하는 토픽에서 수집하는 경우 --permissions 목록에 pubsub.schemas.get을 추가하세요. 그렇지 않은 경우 역할을 최소 권한으로 유지할 수 있도록 추가하지 마세요.
roles/pubsub.editor를 부여할 수 있습니다.
ClickPipe 전용 서비스 계정을 생성합니다:
gcloud iam service-accounts create clickpipes-pubsub \
--project=YOUR_PROJECT_ID \
--display-name="ClickPipes Pub/Sub Ingestion"
roles/pubsub.editor)을 서비스 계정에 바인딩하세요:
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member="serviceAccount:clickpipes-pubsub@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
--role="projects/YOUR_PROJECT_ID/roles/clickpipes.pubsub.ingestion"
gcloud iam service-accounts keys create clickpipes-pubsub-key.json \
--iam-account=clickpipes-pubsub@YOUR_PROJECT_ID.iam.gserviceaccount.com
clickpipes-pubsub-key.json 파일을 ClickPipes UI에 업로드하세요.
키를 민감 정보로 취급하십시오서비스 계정 키는 GCP 프로젝트에 대한 액세스 권한을 부여합니다. 이 파일은 안전하게 보관하고, 버전 관리 시스템에 커밋하지 말고, 정기적으로 교체하십시오. ClickPipes는 업로드 후 키를 저장 시 암호화합니다.
pubsub.topics.attachSubscription 권한은 subscription이 아니라 토픽 리소스에 필요합니다. subscription 수준의 권한만 부여할 때 이 점을 흔히 놓칩니다.- 토픽이 네이티브 Pub/Sub 스키마(schema)(Avro 또는 Protobuf)를 사용하지 않는다면
pubsub.schemas.get 권한은 필요하지 않습니다.
- 관리형 구독의 이름은
clickpipes-{pipeID}이며, ack deadline은 60초, 메시지 보존 기간은 7일이고, 메시지 순서 지정이 활성화됩니다.
- 임시 검색 subscription의 이름은
clickpipes-discovery-{uuid}이며, ack deadline은 10초, 보존 기간은 10분이고, 24시간 후 자동 만료되는 TTL이 적용됩니다.
- ClickPipes는
PermissionDenied 및 Unauthenticated 오류를 재시도 불가로 처리합니다. 권한이 누락되면 파이프는 무기한 재시도하지 않고 즉시 실패합니다.
