> ## 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 source。

> [!NOTE]
>
> GCP Workload Identity 身份验证目前处于 Beta 阶段。

借助 GCP Workload Identity，ClickPipes 无需存储客户的服务账号密钥即可访问受支持的 Google Cloud source。本指南将介绍如何获取由 ClickPipes 管理的 Google 服务账号、授予其访问 source 的权限，以及创建使用短期凭证的 ClickPipe。

## 开始之前

您需要：

* 一个运行在 GCP 上的 ClickHouse Cloud 服务，且其 ClickPipes 部署也必须运行在 GCP 上。
* 一个 ClickHouse Cloud API 密钥，且具有管理该服务上 ClickPipes 的权限。
* 有权在 Google Cloud 源资源上授予 IAM 角色。
* 如使用 Terraform，需使用包含 `clickhouse_clickpipes_service_context` 数据源的 ClickHouse 提供商发行版。选择版本前，请先查看[提供商更新日志](https://github.com/ClickHouse/terraform-provider-clickhouse/releases)。

## 工作原理

1. ClickPipes 会为您的 ClickHouse Cloud 服务创建并管理一个 Google 服务账号。
2. 您从 ClickPipes 服务上下文中获取该服务账号。
3. 您为该服务账号授予访问 Google Cloud 数据源资源的权限。
4. ClickPipes 通过 Workload Identity 为该服务账号获取短期凭证，进而访问数据源。

每个 ClickHouse Cloud 服务都有其唯一的服务账号。您可以通过 Google Cloud IAM 控制该账号对您资源的访问权限，并可随时撤销。网络连接 (包括私有连接) 需另行配置。

## 获取 ClickPipes 服务账号

使用 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` 中返回托管服务账号：
>
> ```json theme={null}
> {
>   "result": {
>     "gcpWorkloadIdentity": {
>       "supported": true,
>       "ready": true,
>       "principal": "ch-example@clickpipes-production.iam.gserviceaccount.com"
>     }
>   }
> }
> ```
>
> 如果该 ClickHouse 服务此前从未使用过 ClickPipes，响应最初可能返回 `ready: false`，且不包含 `principal`。请重试，直到 `ready` 为 `true` 且 `principal` 已填充。
>
> 完整的响应 schema 请参阅[服务上下文 API 参考文档](https://clickhouse.com/docs/zh/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 不受支持，该数据源会直接报错。它会在 `ready_timeout` 时限内等待身份就绪并填充 `principal`。仅当您需要立即获取当前能力状态的快照而无需等待时，才设置 `wait_for_identity = false`。

服务上下文各字段的含义如下：

| 字段 | 含义 |
| - | - |
| `supported` | ClickPipes 部署支持 GCP workload identity。 |
| `ready` | 托管身份及其身份模拟配置已就绪。若 workload identity 不受支持，可能不返回此字段。 |
| `principal` | 需要在您的源资源上授予权限的 Google 服务账号邮箱。在身份就绪之前，可能不返回此字段。 |

## 为 source 授予访问权限

使用 `serviceAccount:<principal>` 作为 IAM 成员，其中 `<principal>` 是服务上下文中返回的电子邮件地址。请仅为其授予 source 所需的角色，具体要求请参阅相应 source 的权限部分：

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

ClickPipes 无法在您的 Google Cloud 项目中创建 IAM 绑定，因此请在创建 ClickPipe 之前先完成授权。如果在同一个 Terraform 配置中同时管理授权和 ClickPipe，请使用 `depends_on` 确保按此顺序执行。

## 创建 ClickPipe

将 source 的身份验证方法设置为 `SERVICE_ACCOUNT_WORKLOAD_IDENTITY`。使用 Workload Identity 时，请勿同时配置服务账号密钥、访问密钥、连接字符串或 IAM role。

各 source 的编程示例请参阅：

* [使用 Terraform 配置 Google Managed Kafka](https://clickhouse.com/docs/zh/integrations/clickpipes/programmatic-access/terraform.md#gcmk-workload-identity)
* [使用 Terraform 配置 Google Cloud Storage](https://clickhouse.com/docs/zh/integrations/clickpipes/programmatic-access/terraform.md#gcs-workload-identity)
* [使用 Terraform 配置 Google Cloud Pub/Sub](https://clickhouse.com/docs/zh/integrations/clickpipes/programmatic-access/terraform.md#pubsub)
* [使用 Terraform 配置 BigQuery](https://clickhouse.com/docs/zh/integrations/clickpipes/programmatic-access/terraform.md#bigquery-workload-identity)
* [OpenAPI 示例](https://clickhouse.com/docs/zh/integrations/clickpipes/programmatic-access/openapi.md#creating-clickpipes)

## 故障排查

> [accordion] 不支持 Workload Identity
>
> 请确认 ClickHouse Cloud 服务及其 ClickPipes 部署均运行在 GCP 上。如果服务满足上述要求，但 `supported` 仍为 `false`，请联系 ClickHouse 支持团队。

> [accordion] 身份尚未就绪
>
> 身份可能仍在预配中。请重试服务上下文请求；如果使用 Terraform，请调大 `ready_timeout`。在 `ready` 变为 `true` 且 `principal` 已填充之前，请勿创建 ClickPipe。

> [accordion] source 拒绝访问
>
> 请确认 IAM 成员为 `serviceAccount:<principal>`，且其中的主体与服务上下文中给出的主体完全一致。检查角色是否已在正确的项目、数据集、桶、订阅或集群作用域上授予。如果使用 Google Managed Kafka，还需检查 broker 端的 Kafka 访问控制列表和 TLS 配置。
