> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickPipes 向け GCP workload identity

> GCP workload identity を使用して、ClickPipes からサポート対象の Google Cloud データソースへのキーレスアクセスを設定します。

> [!NOTE]
>
> 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 プロバイダーのリリース。バージョンを選択する前に、[プロバイダーの変更ログ](https://github.com/ClickHouse/terraform-provider-clickhouse/releases)を確認してください。

## 仕組み

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 を作成しないでください。

> [tab] OpenAPI
>
> API認証情報とリソース ID を設定します:
>
> ```bash theme={null}
> export KEY_ID=<your_key_id>
> export KEY_SECRET=<your_key_secret>
> export ORG_ID=<your_organization_id>
> export SERVICE_ID=<your_service_id>
> ```
>
> サービスコンテキストを取得します:
>
> ```bash theme={null}
> curl -u "$KEY_ID:$KEY_SECRET" \
>   "https://api.clickhouse.cloud/v1/organizations/$ORG_ID/services/$SERVICE_ID/clickpipes/context"
> ```
>
> アイデンティティの準備が完了すると、応答の `principal` にマネージド service account が含まれます:
>
> ```json theme={null}
> {
>   "result": {
>     "gcpWorkloadIdentity": {
>       "supported": true,
>       "ready": true,
>       "principal": "ch-example@clickpipes-production.iam.gserviceaccount.com"
>     }
>   }
> }
> ```
>
> その ClickHouse サービスでまだ ClickPipes を使用したことがない場合、最初の応答では `principal` が含まれず、`ready: false` が返されることがあります。`ready` が `true` になり、`principal` に値が設定されるまで再試行してください。
>
> 応答スキーマの詳細については、[サービスコンテキストのAPIリファレンス](https://clickhouse.com/docs/ja/products/cloud/api-reference/clickpipes/click-pipes-service-context-get)を参照してください。

> [tab] Terraform
>
> `clickhouse_clickpipes_service_context` データソースを使用します:
>
> ```hcl theme={null}
> data "clickhouse_clickpipes_service_context" "service" {
>   service_id    = var.service_id
>   ready_timeout = "2m"
> }
>
> output "clickpipes_gcp_service_account" {
>   value = data.clickhouse_clickpipes_service_context.service.gcp_workload_identity.principal
> }
> ```
>
> デフォルトでは、workload identity がサポートされていない場合、このデータソースはエラーになります。また、アイデンティティの準備が完了して `principal` に値が設定されるまで、最大 `ready_timeout` の間待機します。待機せずに現在のケーパビリティの状態をスナップショットとして取得したい場合に限り、`wait_for_identity = false` を設定してください。

サービスコンテキストの各フィールドの意味は次のとおりです:

| フィールド | 意味 |
| - | - |
| `supported` | ClickPipes のデプロイメントが GCP workload identity をサポートしているかどうか。 |
| `ready` | マネージドアイデンティティとその権限借用の設定の準備が完了しているかどうか。workload identity がサポートされていない場合、このフィールドは省略されることがあります。 |
| `principal` | ソースリソースへのアクセスを許可する Google service account のメールアドレス。アイデンティティの準備が完了するまで、このフィールドは省略されることがあります。 |

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

IAM メンバーには `serviceAccount:<principal>` を使用します。`<principal>` には、サービスコンテキストで返されるメールアドレスを指定します。各ソースのアクセス許可セクションの説明に従い、そのソースに必要なロールのみを付与してください。

* [BigQuery](https://clickhouse.com/docs/ja/integrations/clickpipes/bigquery/overview.md#permissions)
* [Cloud SQL for Postgres](https://clickhouse.com/docs/ja/integrations/clickpipes/postgres/source/google-cloudsql.md#iam-database-authentication)
* [Cloud SQL for MySQL](https://clickhouse.com/docs/ja/integrations/clickpipes/mysql/source/gcp.md#iam-database-authentication)
* [Google Managed Service for Apache Kafka](https://clickhouse.com/docs/ja/integrations/clickpipes/kafka/reference.md#gcp-workload-identity)
* [Google Cloud ストレージ](https://clickhouse.com/docs/ja/integrations/clickpipes/object-storage/gcs/overview.md#permissions)
* [Google Cloud Pub/Sub](https://clickhouse.com/docs/ja/integrations/clickpipes/pubsub/auth.md#use-workload-identity)

ClickPipes は、お客様の Google Cloud プロジェクト内に IAM バインディングを作成できません。ClickPipe を作成する前に、権限を付与しておいてください。権限と ClickPipe を同じ Terraform 設定で管理する場合は、`depends_on` を使用してこの順序を保証してください。

## ClickPipe を作成する

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

各ソースのプログラムによる設定例は、以下を参照してください。

* [Terraform を使用した Google Managed Kafka](https://clickhouse.com/docs/ja/integrations/clickpipes/programmatic-access/terraform.md#gcmk-workload-identity)
* [Terraform を使用した Google Cloud ストレージ](https://clickhouse.com/docs/ja/integrations/clickpipes/programmatic-access/terraform.md#gcs-workload-identity)
* [Terraform を使用した Google Cloud Pub/Sub](https://clickhouse.com/docs/ja/integrations/clickpipes/programmatic-access/terraform.md#pubsub)
* [Terraform を使用した BigQuery](https://clickhouse.com/docs/ja/integrations/clickpipes/programmatic-access/terraform.md#bigquery-workload-identity)
* [OpenAPI の例](https://clickhouse.com/docs/ja/integrations/clickpipes/programmatic-access/openapi.md#creating-clickpipes)

## トラブルシューティング

> [accordion] Workload Identity がサポートされていません
>
> ClickHouse Cloud サービスとその ClickPipes デプロイメントの両方が GCP 上で稼働していることを確認してください。サービスがこれらの要件を満たしているにもかかわらず `supported` が `false` になる場合は、ClickHouse Support にお問い合わせください。

> [accordion] アイデンティティの準備が完了していません
>
> アイデンティティのプロビジョニングがまだ進行中の可能性があります。サービスコンテキストのリクエストを再試行するか、Terraform を使用している場合は `ready_timeout` の値を増やしてください。`ready` が `true` になり、`principal` に値が設定されるまでは、ClickPipe を作成しないでください。

> [accordion] ソースでアクセスが拒否される
>
> IAM メンバーが `serviceAccount:<principal>` の形式になっており、サービスコンテキストから取得したプリンシパルをそのまま使用していることを確認してください。また、ロールが正しいプロジェクト、データセット、バケット、サブスクリプション、またはクラスターのスコープで付与されていることも確認してください。Google Managed Kafka を使用している場合は、ブローカー側の Kafka アクセス制御リストと TLS設定もチェックしてください。
