プライベートプレビューのウェイトリストには、こちらから登録できます。
前提条件
このガイドに従うには、以下が必要です。- 有効な 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 ガイドを参照してください。
- プロジェクト内のトピックを一覧表示して読み取る
- メッセージの消費に ClickPipes が使用する管理対象サブスクリプションを作成および削除する
- そのサブスクリプションからメッセージを消費する
- (任意で) スキーマレジストリから Pub/Sub ネイティブのスキーマを読み取る
必要な権限
ClickPipes では、トピックを所有する GCP プロジェクトに対して、以下の IAM 権限が必要です。これらの権限は、パイプのライフサイクル全体をカバーしており、検出 (トピックの一覧表示、検証、サンプリング) 、サブスクリプション管理、定常運用時のインジェスト、クリーンアップが含まれます。トピックへのアクセス (検出と検証)
サブスクリプションのライフサイクル (検出とインジェスト)
スキーマへのアクセス (任意 — ネイティブ Avro/Protobuf トピックに限る)
定義済みロール
セットアップ
カスタム ロールを作成する (推奨)
最小権限の原則に従い、ClickPipes に必要な権限のみを含むカスタム ロールを作成します。 これはgcloud CLI を使用して実行できます。
オプションの権限ネイティブの 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 にバインドします。
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エラーを再試行不可として扱います。つまり、権限が不足している場合、パイプは無期限に再試行するのではなく、即座に失敗します。