메인 콘텐츠로 건너뛰기
여기에서 비공개 프리뷰 대기자 명단에 등록할 수 있습니다.
이 문서에서는 ClickPipes가 Google Cloud Pub/Sub에 인증하고 토픽에서 데이터를 소비하는 데 필요한 GCP IAM 권한과, ClickPipes가 사용하는 서비스 계정에 액세스 권한을 부여하는 방법을 설명합니다.

사전 요구 사항

이 가이드를 따르려면 다음이 필요합니다.
  • 활성 상태의 ClickHouse Cloud 서비스
  • 수집할 Pub/Sub 토픽이 포함된 GCP 프로젝트
  • 해당 프로젝트에서 역할을 부여할 수 있는 IAM 권한
  • 서비스 계정 키 인증을 사용하는 경우, 서비스 계정과 키를 생성할 수 있는 IAM 권한

인증 모델

Pub/Sub용 ClickPipes는 두 가지 인증 방식을 지원합니다.
  • 서비스 계정 키: Google 서비스 계정을 생성한 후 해당 JSON 키를 ClickPipes UI에서 업로드하거나 API를 통해 제공합니다. ClickPipes는 키를 저장 상태에서 암호화합니다.
  • GCP Workload Identity(베타): ClickPipes가 관리하는 Google 서비스 계정의 단기 자격 증명을 사용합니다. 고객의 서비스 계정 키는 저장되지 않습니다. 요구 사항은 GCP Workload Identity 가이드를 참조하십시오.
어떤 방식을 사용하든 서비스 계정은 다음 작업에 사용됩니다.
  • 프로젝트의 토픽을 나열하고 읽습니다.
  • 메시지를 소비하기 위해 ClickPipes가 사용하는 관리형 구독을 생성하고 삭제합니다.
  • 해당 subscription에서 메시지를 소비합니다.
  • (선택 사항) 스키마 레지스트리에서 네이티브 Pub/Sub 스키마를 읽습니다.

필수 권한

ClickPipes를 사용하려면 토픽을 소유한 GCP 프로젝트에 다음 IAM 권한이 필요합니다. 이러한 권한은 검색(토픽 목록 조회, 검증, 샘플링), subscription 관리, 지속적인 수집, 정리까지 파이프의 전체 수명 주기를 포괄합니다.

토픽 액세스(검색 및 유효성 검사)

subscription 수명 주기(검색 및 수집)

스키마 액세스(선택 사항 — 네이티브 Avro/Protobuf 토픽에만 해당)

사전 정의된 역할

설정

사용자 지정 역할 생성(권장)

최소 권한 원칙에 따라 ClickPipes에 정확히 필요한 권한만 포함된 사용자 지정 역할을 생성하십시오. 다음과 같이 gcloud CLI를 사용해 수행할 수 있습니다:
또는 GCP Console에서 IAM & Admin → Roles → Create role로 이동한 뒤, 필요한 권한에 나열된 권한을 추가하세요.
선택적 권한네이티브 Pub/Sub Avro 또는 Protobuf 스키마를 사용하는 토픽에서 수집하는 경우 --permissions 목록에 pubsub.schemas.get을 추가하세요. 그렇지 않은 경우 역할을 최소 권한으로 유지할 수 있도록 추가하지 마세요.
사용자 지정 역할을 생략하려는 경우에는 대신 roles/pubsub.editor를 부여할 수 있습니다.

GCP Workload Identity 사용 (베타)

GCP Workload Identity 가이드에 따라 서비스 컨텍스트에서 ClickPipes가 관리하는 서비스 계정을 확인하십시오. 생성한 custom 역할 또는 roles/pubsub.editor를 해당 서비스 계정에 바인딩하십시오.
OpenAPI 또는 Terraform을 사용하여 ClickPipe를 생성하고, authentication을 SERVICE_ACCOUNT_WORKLOAD_IDENTITY로 설정하십시오. 이 인증 메서드를 사용할 때는 서비스 계정 키를 제공하지 마십시오.

서비스 계정 생성

서비스 계정 키 인증을 사용하려면 ClickPipe 전용 서비스 계정을 생성합니다:

서비스 계정에 역할 부여

프로젝트 수준에서 생성한 역할(또는 roles/pubsub.editor)을 서비스 계정에 바인딩하세요:

서비스 계정 키 생성 및 다운로드

서비스 계정용 JSON 키를 생성한 다음 로컬로 다운로드합니다:
파이프를 생성할 때 이 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 오류를 재시도 불가로 처리합니다. 권한이 누락되면 파이프는 무기한 재시도하지 않고 즉시 실패합니다.