> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 适用于 ClickPipes 的 GCP Private Service Connect

> 使用 Private Service Connect (PSC) 在 ClickPipes 与托管在 GCP 上的数据源之间建立安全连接。

export const Image = ({img, alt, size = "lg", background}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} style={{
    backgroundColor
  }} />
      </Frame>
    </div>;
};

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

<Check>
  ClickPipes 通过[全局访问](https://docs.cloud.google.com/vpc/docs/about-accessing-vpc-hosted-services-endpoints#global-access)支持**跨区域** PSC 连接。对于位于与运行 ClickPipes 基础设施所在区域不同区域的端点，必须启用全局访问。有关更多详情，请查看 [ClickPipes GCP 区域文档](/zh/integrations/clickpipes/networking/static-ips#google-cloud-static-nat-ips)。
</Check>

<div id="supported-patterns">
  ## 支持的模式
</div>

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

<div id="prerequisites">
  ## 前置条件
</div>

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

<div id="create-rpe">
  ## 创建反向专用终结点
</div>

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

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

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

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

    ```hcl theme={null}
    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>" }
      ]
    }
    ```
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    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>" }
        ]
      }'
    ```
  </Tab>
</Tabs>

<div id="custom-private-dns-rules">
  ### 自定义私有 DNS 名称
</div>

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

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

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

<div id="producer-owned">
  ## 批准生产者拥有的连接
</div>

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

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

```bash theme={null}
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`：

<Danger>
  `--consumer-accept-list` 会覆盖接受列表，而非将新的消费者项目追加到列表中。如果服务附件已接受其他项目或端点，请在同一命令中传入所有项目或端点，否则未传入的项目或端点将失去访问权限。
</Danger>

```bash theme={null}
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
```

<Warning>
  请勿在此处使用 ClickPipes API/Terraform 响应中的 `endpoint_id`；该值是转发规则的*名称*，而非 GCP 要求的数字 ID，因此不会与接受列表匹配。应始终从服务附件中处于待处理状态的 `endpointWithId` 获取数字 ID。
</Warning>

<div id="managing-rpes">
  ## 管理反向专用终结点
</div>

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

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

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

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

要更改端点的自定义私有 DNS 映射，请使用 [Cloud API](/zh/integrations/clickpipes/programmatic-access/openapi) 或 [Terraform](/zh/integrations/clickpipes/programmatic-access/terraform)。更新操作会替换整个映射列表，而不是在其中添加映射。

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

<div id="limitations">
  ## 已知限制
</div>

* 一个 PSC 服务附件在同一时间只能由一个 ClickHouse Cloud 服务认领，不能在多个服务之间重复使用。若要将服务附件迁移到其他服务，请[联系 ClickHouse 支持团队](https://clickhouse.com/support/program)以解除现有认领。