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

​
前提条件

このガイドに従うには、以下が必要です。
  • 有効な ClickHouse Cloud サービス
  • 取り込み元の Pub/Sub トピックを含む GCP プロジェクト
  • そのプロジェクトで サービスアカウント を作成し、ロールを付与するための IAM 権限

​
認証モデル

Pub/Sub 向け ClickPipes は、サービスアカウント JSON キーを使って GCP に認証します。パイプの作成時にキーファイルをアップロードすると、ClickPipes はそれを保存時に暗号化し、実行時には次の目的で使用します。
  • プロジェクト内のトピックを一覧表示して読み取る
  • メッセージの消費に ClickPipes が使用する管理対象サブスクリプションを作成および削除する
  • そのサブスクリプションからメッセージを消費する
  • (任意で) スキーマレジストリから Pub/Sub ネイティブのスキーマを読み取る
現在のところ、Workload Identity や認証情報を直接貼り付けるオプションには対応していません。サポートされている認証方式は、サービスアカウント JSON キーのみです。

​
必要な権限

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

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

Permission目的
pubsub.topics.list検出時に、プロジェクト内で利用可能なトピックを一覧表示する
pubsub.topics.getトピックの存在を検証し、スキーマ設定を取得する
pubsub.topics.attachSubscriptionその トピック に対するサブスクリプションを作成する際に必要

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

PermissionPurpose
pubsub.subscriptions.create管理対象サブスクリプション (clickpipes-{pipeID}) と一時的な検出用サブスクリプションを作成
pubsub.subscriptions.getヘルスチェック (60秒ごと) 、フォロワーのポーリング、サブスクリプションの検証
pubsub.subscriptions.delete一時的な検出用サブスクリプションをクリーンアップし、パイプの削除時に管理対象サブスクリプションを削除
pubsub.subscriptions.consumeReceive()、Ack()、Nack()、およびタイムスタンプへのシーク操作

​
スキーマへのアクセス (任意 — ネイティブ Avro/Protobuf トピックに限る)

PermissionPurpose
pubsub.schemas.getPub/Sub のスキーマレジストリからネイティブ スキーマ定義を取得する

​
定義済みロール

ロール十分か備考
roles/pubsub.editorはい必要な権限をすべてカバーします。最も広範な選択肢です。
roles/pubsub.subscriberいいえtopics.list、topics.attachSubscription、subscriptions.create、subscriptions.delete、schemas.get が不足しています。
roles/pubsub.viewerいいえ読み取り専用 — サブスクリプションの管理やメッセージの消費はできません。
カスタムロール (推奨)はい最小権限でアクセスするには、上記の 7 つの中核権限 (必要に応じて schemas.get を追加) を使用してください。

​
セットアップ

​
カスタム ロールを作成する (推奨)

最小権限の原則に従い、ClickPipes に必要な権限のみを含むカスタム ロールを作成します。 これは 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
または、GCP Console で IAM & Admin → Roles → Create role に移動し、必要な権限に記載の権限を追加します。
オプションの権限ネイティブの 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"

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

サービスアカウント用の JSON キーを作成し、ローカルにダウンロードします。 
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 は、サブスクリプションではなく トピックリソース に対して必要です。サブスクリプション レベルの権限だけを付与している場合、これを見落とすことがよくあります。
  • トピックがネイティブな 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 エラーを再試行不可として扱います。つまり、権限が不足している場合、パイプは無期限に再試行するのではなく、即座に失敗します。
最終更新日 2026年6月10日