Skip to main content
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 提供商发行版。选择版本前,请先查看提供商更新日志。

工作原理

  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。
设置您的 API 凭据和资源 ID:
获取服务上下文:
身份就绪后,响应会在 principal 中返回托管服务账号:
如果该 ClickHouse 服务此前从未使用过 ClickPipes,响应最初可能返回 ready: false,且不包含 principal。请重试,直到 ready 为 true 且 principal 已填充。完整的响应 schema 请参阅服务上下文 API 参考文档。
服务上下文各字段的含义如下:

为 source 授予访问权限

使用 serviceAccount:<principal> 作为 IAM 成员,其中 <principal> 是服务上下文中返回的电子邮件地址。请仅为其授予 source 所需的角色,具体要求请参阅相应 source 的权限部分: ClickPipes 无法在您的 Google Cloud 项目中创建 IAM 绑定,因此请在创建 ClickPipe 之前先完成授权。如果在同一个 Terraform 配置中同时管理授权和 ClickPipe,请使用 depends_on 确保按此顺序执行。

创建 ClickPipe

将 source 的身份验证方法设置为 SERVICE_ACCOUNT_WORKLOAD_IDENTITY。使用 Workload Identity 时,请勿同时配置服务账号密钥、访问密钥、连接字符串或 IAM role。 各 source 的编程示例请参阅:

故障排查

请确认 ClickHouse Cloud 服务及其 ClickPipes 部署均运行在 GCP 上。如果服务满足上述要求,但 supported 仍为 false,请联系 ClickHouse 支持团队。
身份可能仍在预配中。请重试服务上下文请求;如果使用 Terraform,请调大 ready_timeout。在 ready 变为 true 且 principal 已填充之前,请勿创建 ClickPipe。
请确认 IAM 成员为 serviceAccount:<principal>,且其中的主体与服务上下文中给出的主体完全一致。检查角色是否已在正确的项目、数据集、桶、订阅或集群作用域上授予。如果使用 Google Managed Kafka,还需检查 broker 端的 Kafka 访问控制列表和 TLS 配置。