Skip to main content
GCP workload identity 認証は現在ベータ版です。
GCP workload identity を使用すると、ClickPipes はお客様の サービスアカウントキーを保存することなく、サポート対象の Google Cloud ソースにアクセスできます。このガイドでは、ClickPipes が管理する Google service account を取得し、そのアカウントにソースへのアクセス権限を付与したうえで、有効期間の短い認証情報を使用する ClickPipe を作成する手順を説明します。

始める前に

以下が必要です。
  • GCP 上で稼働している ClickHouse Cloud サービス。また、そのサービスの ClickPipes デプロイメントも GCP 上で稼働している必要があります。
  • 対象サービスで ClickPipes を管理するアクセス許可を持つ ClickHouse Cloud APIキー。
  • Google Cloud のソースリソースに対して IAM roleを付与するアクセス許可。
  • Terraform を使用する場合は、clickhouse_clickpipes_service_context データソースを含む ClickHouse プロバイダーのリリース。バージョンを選択する前に、プロバイダーの変更ログを確認してください。

仕組み

  1. ClickPipes が、ClickHouse Cloud サービス用の Google service account を作成・管理します。
  2. ユーザーは、ClickPipes のサービスコンテキストからその service account を取得します。
  3. Google Cloud 上のソースリソースへのアクセス権限を、その service account に付与します。
  4. ClickPipes は Workload Identity を使用して service account の有効期間の短い認証情報を取得し、ソースにアクセスします。
service account は ClickHouse Cloud サービスごとに一意です。リソースへのアクセスは Google Cloud IAM で制御でき、いつでも取り消せます。プライベート接続を含むネットワーク接続は別途設定します。

ClickPipes の service account を取得する

OpenAPI または Terraform を使用して、サービスコンテキストを取得します。workload identity がサポートされており、準備が完了していることがコンテキストで確認できるまでは、ClickPipe を作成しないでください。
API認証情報とリソース ID を設定します:
サービスコンテキストを取得します:
アイデンティティの準備が完了すると、応答の principal にマネージド service account が含まれます:
その ClickHouse サービスでまだ ClickPipes を使用したことがない場合、最初の応答では principal が含まれず、ready: false が返されることがあります。ready が true になり、principal に値が設定されるまで再試行してください。応答スキーマの詳細については、サービスコンテキストのAPIリファレンスを参照してください。
サービスコンテキストの各フィールドの意味は次のとおりです:

ソースへのアクセス権を付与する

IAM メンバーには serviceAccount:<principal> を使用します。<principal> には、サービスコンテキストで返されるメールアドレスを指定します。各ソースのアクセス許可セクションの説明に従い、そのソースに必要なロールのみを付与してください。 ClickPipes は、お客様の Google Cloud プロジェクト内に IAM バインディングを作成できません。ClickPipe を作成する前に、権限を付与しておいてください。権限と ClickPipe を同じ Terraform 設定で管理する場合は、depends_on を使用してこの順序を保証してください。

ClickPipe を作成する

ソースの認証方式を SERVICE_ACCOUNT_WORKLOAD_IDENTITY に設定します。Workload Identity を使用する場合は、サービスアカウントキー、アクセスキー、接続文字列、IAM role のいずれも併せて設定しないでください。 各ソースのプログラムによる設定例は、以下を参照してください。

トラブルシューティング

ClickHouse Cloud サービスとその ClickPipes デプロイメントの両方が GCP 上で稼働していることを確認してください。サービスがこれらの要件を満たしているにもかかわらず supported が false になる場合は、ClickHouse Support にお問い合わせください。
アイデンティティのプロビジョニングがまだ進行中の可能性があります。サービスコンテキストのリクエストを再試行するか、Terraform を使用している場合は ready_timeout の値を増やしてください。ready が true になり、principal に値が設定されるまでは、ClickPipe を作成しないでください。
IAM メンバーが serviceAccount:<principal> の形式になっており、サービスコンテキストから取得したプリンシパルをそのまま使用していることを確認してください。また、ロールが正しいプロジェクト、データセット、バケット、サブスクリプション、またはクラスターのスコープで付与されていることも確認してください。Google Managed Kafka を使用している場合は、ブローカー側の Kafka アクセス制御リストと TLS設定もチェックしてください。