适用于 ClickPipes 的 GCP Private Service Connect

您可以使用 GCP Private Service Connect (PSC)，在 ClickPipes 与托管在 GCP 上的数据源之间建立安全连接。ClickPipes 会在其 VPC 中创建一个反向专用终结点 (RPE)，并将其指向为您的数据源发布的专用端点服务，确保流量不会暴露于公网。

支持的模式

模式	适用场景	服务附件
原生 PSC	自动发布 PSC 服务附件的托管服务 (例如 Google Cloud SQL、AlloyDB、Google Cloud Managed Service for Apache Kafka) 。	在实例上启用 PSC 时自动创建。
生产者拥有的 PSC	不发布服务附件的数据源，例如运行在 Compute Engine 上的 Postgres，或仅能通过私网 IP 访问的托管服务。	由您创建和管理。

前置条件

托管于 GCP 上的 ClickHouse Cloud 服务。ClickPipes 与您的 ClickHouse Cloud 服务运行在同一区域 (少数例外情况除外) 。
用于在源端启用 PSC 以及管理 PSC 服务附件的 IAM 权限 (roles/compute.networkAdmin) 。
获准连接您的服务附件的 ClickPipes 消费者项目 (clickpipes-production)。
如果以编程方式预配 ClickPipes：服务所属组织的 ClickHouse Cloud API 密钥。

创建反向专用终结点

要创建 RPE，您需要准备数据源的以下信息：

服务附件 URI：projects/<PROJECT>/regions/<REGION>/serviceAttachments/<NAME>，即位于数据源前端的 PSC 端点。
私有 DNS 名称：管道要连接的主机名。PSC 端点会获得一个未关联 DNS 名称的静态内部 IP，因此 ClickPipes 会为您将该主机名解析为此 IP。

在 ClickHouse Cloud 中，打开您的服务并前往 数据源 > ClickPipes。
选择要摄取的数据源。
在 设置 ClickPipe 连接 下，开启 使用安全连接，然后点击 + 反向专用终结点，并选择 GCP PSC 服务附件。
填写 服务附件 URI、私有 DNS 名称和描述。
点击创建。端点状态将从 Provisioning 变为 Ready。 (原生 PSC 会自动接受，因此不会显示 PendingAcceptance。)

自定义私有 DNS 映射不是 clickhouse_clickpipes_reverse_private_endpoint 的属性，而是由独立的 clickhouse_clickpipes_reverse_private_endpoint_custom_private_dns 资源管理。该资源接受完整的映射替换列表，并通过 ID 引用端点：

resource "clickhouse_clickpipes_reverse_private_endpoint" "gcp_psc" {
  service_id             = var.clickhouse_service_id
  description            = "GCP PSC endpoint"
  type                   = "GCP_PSC_SERVICE_ATTACHMENT"
  gcp_service_attachment = "projects/<PROJECT>/regions/<REGION>/serviceAttachments/<NAME>"
}

resource "clickhouse_clickpipes_reverse_private_endpoint_custom_private_dns" "gcp_psc" {
  service_id                  = var.clickhouse_service_id
  reverse_private_endpoint_id = clickhouse_clickpipes_reverse_private_endpoint.gcp_psc.id

  mapping = [
    { private_dns_name = "<PRIVATE_DNS_NAME>" }
  ]
}

curl --silent --user $KEY_ID:$KEY_SECRET \
  -X POST -H "Content-Type: application/json" \
  https://api.clickhouse.cloud/v1/organizations/<ORG_ID>/services/<SERVICE_ID>/clickpipesReversePrivateEndpoints \
  -d '{
    "type": "GCP_PSC_SERVICE_ATTACHMENT",
    "description": "GCP PSC endpoint",
    "gcpServiceAttachment": "projects/<PROJECT>/regions/<REGION>/serviceAttachments/<NAME>",
    "customPrivateDnsMappings": [
      { "privateDnsName": "<PRIVATE_DNS_NAME>" }
    ]
  }'

自定义私有 DNS 名称

由于 GCP PSC 不会传播 DNS，每个 GCP PSC 端点都需要自定义私有 DNS 映射，以便 ClickPipes 将其解析为该端点的静态内部 IP。

标准的 ClickPipes 自定义私有 DNS 命名规则同样适用：所有提供商均以相同方式支持通配符，并强制要求服务的反向专用终结点之间保持唯一性，同时遵守保留后缀限制。通配符尤其有用，例如，单个映射 (如 *.<cluster>.<region>.managedkafka.<project>.cloud.goog) 即可覆盖 Managed Kafka 集群中的每个 broker。

对于 GCP PSC，仅使用映射的 privateDnsName。不支持 internalDNSName 字段，因为 PSC 端点提供的是静态 IP，没有可供绑定的 DNS 名称：映射始终会解析到该 IP。

批准生产者拥有的连接

对于生产者拥有的 PSC，请将 ClickPipes 消费者项目 (clickpipes-production) 添加到服务附件的自动接受列表，以便自动接受该连接。如果跳过此步骤，RPE 将一直处于 PendingAcceptance 状态，直到您手动批准。

要接受该连接，服务附件的消费者接受列表中需要包含端点的基于数字 ID 的 URI (projects/<PROJECT>/regions/<REGION>/forwardingRules/<NUMERIC_ID>)。要获取服务附件上待处理连接的 endpointWithId 值，请运行：

gcloud beta compute service-attachments describe <SERVICE_ATTACHMENT_NAME> \
  --region=<REGION> --project=<YOUR_PROJECT_ID> \
  --format='json(connectedEndpoints)'

获取 status 为 PENDING 的条目的 endpointWithId，去掉 https://www.googleapis.com/compute/beta/ 前缀，然后将结果传递给 --consumer-accept-list：

gcloud beta compute service-attachments update <SERVICE_ATTACHMENT_NAME> \
  --region=<REGION> --project=<YOUR_PROJECT_ID> \
  --consumer-accept-list=projects/<PROJECT>/regions/<REGION>/forwardingRules/<NUMERIC_ID> \
  --reconcile-connections

管理反向专用终结点

您可以在 ClickHouse Cloud 服务设置中管理现有的反向专用终结点：

在 ClickHouse Cloud 控制台侧边栏中，前往 Settings。

在 ClickPipe reverse private endpoints 下，点击 Reverse private endpoints。

反向专用终结点的详细信息会显示在弹出面板中。您可以在此视图中删除 RPE：点击端点旁的 ×，然后确认删除。删除操作是永久性的，会导致所有当前使用该端点的 ClickPipe 中断。

要更改端点的自定义私有 DNS 映射，请使用 Cloud API 或 Terraform。更新操作会替换整个映射列表，而不是在其中添加映射。

如果端点显示 Rejected 或 Failed，请查看其状态下方的消息：该消息可区分被生产者拒绝的连接，以及已关闭或需要处理的连接。这两种情况通常都表示服务附件的接受列表未包含 ClickPipes 消费者项目。要查看 GCP 针对该端点报告的状态，请描述服务附件的 connectedEndpoints。

已知限制

一个 PSC 服务附件在同一时间只能由一个 ClickHouse Cloud 服务认领，不能在多个服务之间重复使用。若要将服务附件迁移到其他服务，请联系 ClickHouse 支持团队以解除现有认领。