メインコンテンツへスキップ
プライベートプレビューのウェイトリストには、こちらから登録できます。
この記事では、ClickPipes が Google Cloud Pub/Sub に対して認証を行い、トピックからデータを読み取るため、また ClickPipes が使用する service account にアクセスを付与するために必要な GCP IAM 権限について説明します。

前提条件

このガイドに従うには、以下が必要です。
  • 有効な ClickHouse Cloud サービス
  • 取り込み元の Pub/Sub トピックを含む GCP プロジェクト
  • そのプロジェクトでロールを付与するための IAM 権限
  • service account キーによる認証を使用する場合は、service account とキーを作成するための IAM 権限

認証モデル

Pub/Sub 向け ClickPipes は、次の 2 つの認証方式をサポートしています。
  • サービスアカウントキー: Google の service account を作成し、その JSON キーを ClickPipes UI でアップロードするか、API 経由で指定します。ClickPipes はキーを保存時に暗号化します。
  • GCP Workload Identity (ベータ): ClickPipes は、ClickPipes が管理する Google service account の有効期間の短い認証情報を使用します。お客様のサービスアカウントキーは保存されません。要件については GCP Workload Identity ガイドを参照してください。
いずれの方式でも、service account は次の目的で使用されます。
  • プロジェクト内のトピックを一覧表示して読み取る
  • メッセージの消費に ClickPipes が使用する管理対象サブスクリプションを作成および削除する
  • そのサブスクリプションからメッセージを消費する
  • (任意で) スキーマレジストリから Pub/Sub ネイティブのスキーマを読み取る

必要な権限

ClickPipes では、トピックを所有する GCP プロジェクトに対して、以下の IAM 権限が必要です。これらの権限は、パイプのライフサイクル全体をカバーしており、検出 (トピックの一覧表示、検証、サンプリング) 、サブスクリプション管理、定常運用時のインジェスト、クリーンアップが含まれます。

トピックへのアクセス (検出と検証)

サブスクリプションのライフサイクル (検出とインジェスト)

スキーマへのアクセス (任意 — ネイティブ 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 が管理する service account を取得します。 作成したカスタムロール、または roles/pubsub.editor を、その service account にバインドします。
OpenAPI または Terraform を使用し、authentication を SERVICE_ACCOUNT_WORKLOAD_IDENTITY に設定して ClickPipe を作成します。この認証方式を使用する場合は、サービスアカウントキーを指定しないでください。

service account を作成する

service account キー認証を使用する場合は、ClickPipe専用の service account を作成します。

サービスアカウントにロールを付与する

作成したロール (または roles/pubsub.editor) を、プロジェクトレベルでサービスアカウントにバインドします。

サービスアカウント キーを作成してダウンロードする

サービスアカウント用の JSON キーを作成し、ローカルにダウンロードします。
この clickpipes-pubsub-key.json ファイルは、パイプの作成時に ClickPipes UI でアップロードします。
このキーは機密情報として扱ってくださいサービスアカウントキーには、GCP プロジェクトへのアクセス権が付与されています。ファイルは安全に保管し、ソース管理にコミットせず、定期的にローテーションしてください。ClickPipes では、アップロード後、このキーは保存時に暗号化されます。

注意事項

  • pubsub.topics.attachSubscription は、サブスクリプションではなく トピックリソース に対して必要です。サブスクリプション レベルの権限だけを付与している場合、これを見落とすことがよくあります。
  • トピックがネイティブな Pub/Sub スキーマ (Avro または Protobuf) を使用していない場合、pubsub.schemas.get 権限は不要です。
  • 管理対象サブスクリプションの名前は clickpipes-{pipeID} で、ack deadline は 60 秒、メッセージ保持期間は 7 日間、メッセージの順序付けは有効です。
  • 一時的な 検出 サブスクリプションの名前は clickpipes-discovery-{uuid} で、ack deadline は 10 秒、保持期間は 10 分、24 時間で自動期限切れとなる有効期限 (TTL) が設定されます。
  • ClickPipes は PermissionDenied および Unauthenticated エラーを再試行不可として扱います。つまり、権限が不足している場合、パイプは無期限に再試行するのではなく、即座に失敗します。