> ## 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.

> 使用 AWS PrivateLink 在 ClickPipes 与数据源之间建立安全连接。

# ClickPipes 的 AWS PrivateLink

export const PrivatePreviewBadge = () => {
  return <div className="privatePreviewBadge">
            <div className="privatePreviewIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path d="M5.33301 6.66667V4.66667V4.66667C5.33301 3.194 6.52701 2 7.99967 2V2C9.47234 2 10.6663 3.194 10.6663 4.66667V4.66667V6.66667" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path d="M8.00033 9.33337V11.3334" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path fillRule="evenodd" clipRule="evenodd" d="M11.333 14H4.66634C3.92967 14 3.33301 13.4033 3.33301 12.6666V7.99996C3.33301 7.26329 3.92967 6.66663 4.66634 6.66663H11.333C12.0697 6.66663 12.6663 7.26329 12.6663 7.99996V12.6666C12.6663 13.4033 12.0697 14 11.333 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            {'ClickHouse Cloud 私有预览'}
        </div>;
};

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

您可以使用 [AWS PrivateLink](https://aws.amazon.com/privatelink/) 在 ClickPipes 与托管在 AWS 上的数据源之间建立安全连接。ClickPipes 会在其 VPC 中创建**反向专用终结点 (RPE)**，并将其指向为您的数据源发布的专用终结点服务，确保流量不会暴露于公网。

<Note>
  开始前，请查看[支持的 AWS 区域](#aws-privatelink-regions)。
</Note>

<div id="supported-sources">
  ## 支持的 ClickPipes 数据源
</div>

ClickPipes 反向专用终结点功能仅支持以下
数据源类型：

* Kafka
* Postgres
* MySQL
* MongoDB

<Note>
  对于 Kafka，[与 Confluent 兼容的 Schema Registry](/docs/zh/integrations/clickpipes/kafka/schema-registries#confluent-compatible-registries) 可通过与消息代理相同的反向专用终结点访问，无需暴露在公网；前提是其主机名解析为该端点的私网 IP 地址。
</Note>

<div id="aws-privatelink-endpoint-types">
  ## 支持的 AWS PrivateLink 端点类型
</div>

ClickPipes 反向专用终结点可配置为使用以下任一种 AWS PrivateLink 方式：

* [VPC 资源](#vpc-resource)
* [适用于 MSK ClickPipe 的 MSK 多 VPC 连接](#msk-multi-vpc)
* [VPC endpoint service](#vpc-endpoint-service)

<div id="vpc-resource">
  ### VPC 资源
</div>

<Info>
  不支持跨区域。
</Info>

您可以通过 [PrivateLink](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-access-resources.html) 在 ClickPipes 中访问 VPC 资源。此方法无需在数据源前部署负载均衡器。

资源配置可指定特定主机或 RDS 集群 ARN。

对于从 RDS 集群摄取数据的 Postgres CDC (变更数据捕获) ，这是首选方案。

要为 VPC 资源设置 PrivateLink：

1. 创建资源网关
2. 创建资源配置
3. 创建资源共享

<Steps>
  <Step title="创建资源网关" id="create-resource-gateway">
    资源网关是接收发往 VPC 中指定资源流量的入口。

    <Note>
      建议为关联到资源网关的子网保留充足的可用 IP 地址。
      建议每个子网的子网掩码至少为 `/26`。

      对于每个 VPC 端点 (即每个 Reverse Private Endpoint) ，AWS 要求每个子网提供一块由 16 个连续 IP 地址组成的地址块 (`/28` 子网掩码) 。
      如果不满足此要求，Reverse Private Endpoint 将进入失败状态。
    </Note>

    您可以通过 [AWS 控制台](https://docs.aws.amazon.com/vpc/latest/privatelink/create-resource-gateway.html)或使用以下命令创建资源网关：

    ```bash theme={null}
    aws vpc-lattice create-resource-gateway \
        --vpc-identifier <VPC_ID> \
        --subnet-ids <SUBNET_IDS> \
        --security-group-ids <SG_IDs> \
        --name <RESOURCE_GATEWAY_NAME>
    ```

    输出中将包含资源网关 ID，下一步需要用到它。

    继续之前，您需要等待资源网关进入 `Active` 状态。您可以运行以下命令检查其状态：

    ```bash theme={null}
    aws vpc-lattice get-resource-gateway \
        --resource-gateway-identifier <RESOURCE_GATEWAY_ID>
    ```
  </Step>

  <Step title="创建 VPC 资源配置" id="create-resource-configuration">
    资源配置与资源网关关联，使您的资源可被访问。

    您可以通过 [AWS 控制台](https://docs.aws.amazon.com/vpc/latest/privatelink/create-resource-configuration.html)或使用以下命令创建资源配置：

    ```bash theme={null}
    aws vpc-lattice create-resource-configuration \
        --resource-gateway-identifier <RESOURCE_GATEWAY_ID> \
        --type <RESOURCE_CONFIGURATION_TYPE> \
        --resource-configuration-definition <RESOURCE_CONFIGURATION_DEFINITION> \
        --name <RESOURCE_CONFIGURATION_NAME>
    ```

    最简单的[资源配置类型](https://docs.aws.amazon.com/vpc-lattice/latest/ug/resource-configuration.html#resource-configuration-types)是单个资源配置。您可以直接使用 ARN 进行配置，也可以共享可通过公网解析的 IP 地址或域名。

    例如，使用 RDS 集群的 ARN 进行配置：

    ```bash theme={null}
    aws vpc-lattice create-resource-configuration \
        --name my-rds-cluster-config \
        --type ARN \
        --resource-gateway-identifier rgw-0bba03f3d56060135 \
        --resource-configuration-definition 'arnResource={arn=arn:aws:rds:us-east-1:123456789012:cluster:my-rds-cluster}'
    ```

    <Note>
      无法为可通过公网访问的集群创建资源配置。
      如果你的集群可通过公网访问，必须先将该集群修改为私网，
      然后才能创建资源配置，或者改用 [IP 允许列表](/docs/zh/integrations/clickpipes/networking/static-ips)。
      有关详细信息，请参阅 [AWS 文档](https://docs.aws.amazon.com/vpc/latest/privatelink/resource-configuration.html#resource-definition)。
    </Note>

    输出中将包含资源配置 ARN，下一步需要用到它。输出中还将包含资源配置 ID，用于通过 VPC 资源设置 ClickPipe 连接。
  </Step>

  <Step title="创建资源共享" id="create-resource-share">
    共享资源需要创建 Resource-Share，可通过 Resource Access Manager (RAM) 创建。

    <Note>
      一个 Resource-Share 只能用于一个 Reverse Private Endpoint，且不能重复使用。
      如果需要将同一 Resource-Configuration 用于多个 Reverse Private Endpoint，
      则必须为每个端点分别创建 Resource-Share。
      删除 Reverse Private Endpoint 后，Resource-Share 仍会保留在您的 AWS 账户中；
      如果不再需要，必须手动删除。
    </Note>

    您可以通过 [AWS 控制台](https://docs.aws.amazon.com/ram/latest/userguide/working-with-sharing-create.html) 将 Resource-Configuration 添加到 Resource-Share，也可以使用 ClickPipes 账户 ID `072088201116` (arn:aws:iam::072088201116:root) 运行以下命令：

    ```bash theme={null}
    aws ram create-resource-share \
        --principals 072088201116 \
        --resource-arns <RESOURCE_CONFIGURATION_ARN> \
        --name <RESOURCE_SHARE_NAME>
    ```

    输出中会包含一个资源共享 ARN，使用 VPC 资源设置 ClickPipe 连接时需要用到该 ARN。

    现在，您可以使用 VPC 资源[创建具有反向专用端点的 ClickPipe](#creating-clickpipe)。您需要：

    * 将 `VPC endpoint type` 设置为 `VPC Resource`。
    * 将 `Resource configuration ID` 设置为步骤 2 中创建的资源配置的 ID。
    * 将 `Resource share ARN` 设置为步骤 3 中创建的资源共享的 ARN。

    有关通过 VPC 资源使用 PrivateLink 的更多信息，请参阅 [AWS 文档](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-access-resources.html)。
  </Step>
</Steps>

<div id="msk-multi-vpc">
  ### MSK multi-VPC connectivity
</div>

[Multi-VPC connectivity](https://docs.aws.amazon.com/msk/latest/developerguide/aws-access-mult-vpc.html) 是 AWS MSK 的内置功能，可将多个 VPC 连接到同一个 MSK 集群。
原生支持私有 DNS，无需进行额外配置。
不支持跨区域连接。

这是 ClickPipes for MSK 的推荐选项。
有关详细信息，请参阅[入门](https://docs.aws.amazon.com/msk/latest/developerguide/mvpc-getting-started.html)指南。

<Info>
  更新 MSK 集群策略，并将 `072088201116` 添加到允许的主体列表中。
  有关详细信息，请参阅 AWS 的[附加集群策略](https://docs.aws.amazon.com/msk/latest/developerguide/mvpc-cluster-owner-action-policy.html)指南。
</Info>

请参阅我们的 [ClickPipes MSK 设置指南](/docs/zh/resources/support-center/knowledge-base/cloud-services/aws-privatelink-setup-for-msk-clickpipes)，了解如何设置连接。

<div id="vpc-endpoint-service">
  ### VPC endpoint service
</div>

[VPC endpoint service](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-share-your-services.html) 是与 ClickPipes 共享数据源的另一种方式。
这种方式需要在数据源前部署 NLB (Network Load Balancer) ，
并将 VPC endpoint service 配置为使用该 NLB。

VPC endpoint service 可以[配置私有 DNS](https://docs.aws.amazon.com/vpc/latest/privatelink/manage-dns-names.html)，使其能够在 ClickPipes VPC 中访问。
AWS PrivateLink 托管的私有 DNS 并不总是可行：

* 您不拥有数据源的域名，因此无法通过 AWS 进行验证
* 提供商要求消费者自行管理 DNS 解析，例如 Confluent Cloud
  在这些情况下，请参阅[自定义私有 DNS](#custom-private-dns)。

它是以下场景的首选方案：

* 任何需要私有 DNS 支持的本地部署 Kafka 环境
* [Confluent Cloud 私有连接](/docs/zh/resources/support-center/knowledge-base/cloud-services/confluent-cloud-private-connectivity-for-clickpipes)
* [Postgres CDC 的跨区域连接](/docs/zh/resources/support-center/knowledge-base/cloud-services/aws-privatelink-setup-for-clickpipes)
* [MSK 集群的跨区域连接](/docs/zh/resources/support-center/knowledge-base/cloud-services/aws-privatelink-vpc-endpoint-service-for-msk-cluster)

有关详细信息，请参阅[入门](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-share-your-services.html)指南。

<Info>
  将 ClickPipes 账户 ID `072088201116` 添加到 VPC endpoint service 的允许的主体中。
  有关详细信息，请参阅 AWS 的[权限管理](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions)指南。
</Info>

<Info>
  可为 ClickPipes 配置[跨区域访问](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-share-your-services.html#endpoint-service-cross-region)。
  将[您的 ClickPipe 区域](#aws-privatelink-regions)添加到 VPC endpoint service 的允许区域中。
</Info>

对于 MSK 集群，请参阅 [MSK 集群的 AWS PrivateLink VPC endpoint service](/docs/zh/resources/support-center/knowledge-base/cloud-services/aws-privatelink-vpc-endpoint-service-for-msk-cluster)，
了解使用自定义私有 DNS 名称、为每个 broker 配置一个 endpoint service 的设置。

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

<PrivatePreviewBadge />

<Info>
  自定义私有 DNS 目前处于**私有预览**阶段。请联系 [ClickHouse 支持团队](https://clickhouse.com/support/program)，为您的服务启用此功能。
</Info>

AWS PrivateLink 可为具有已验证域名的 [VPC endpoint service](https://docs.aws.amazon.com/vpc/latest/privatelink/manage-dns-names.html)
提供托管私有 DNS。某些服务要求每个消费者在各自的 VPC 中管理 DNS 解析。例如，Confluent Cloud 要求消费者将 broker 主机名解析为 PrivateLink 端点。

对于此类情况，ClickPipes 支持将自定义私有 DNS name 附加到反向专用
终结点。ClickPipes 会将这些名称解析为该端点的私有地址，使您可通过私有连接使用数据
源自身的主机名访问数据源。

自定义私有 DNS 是对托管私有 DNS 的补充，而非替代。如果您的
PrivateLink 服务已提供私有 DNS name，则无需使用自定义名称。

[VPC endpoint service](#vpc-endpoint-service)
和 [VPC 资源](#vpc-resource)端点类型支持自定义私有 DNS name。MSK multi-VPC 原生提供托管私有 DNS，
且不支持自定义名称。

<Note>
  ClickHouse Cloud 控制台目前每个反向专用终结点仅支持一个自定义私有 DNS name。
  如果需要在同一端点上管理多个自定义私有 DNS name，请使用 OpenAPI 或 Terraform。
</Note>

自定义私有 DNS name 需遵循以下规则：

* 支持精确名称 (`kafka.internal.example.com`) 和通配符名称 (`*.example.com`) 。通配符可匹配单个 DNS 标签。例如，
  `*.abcde12345.us-east-1.aws.confluent.cloud` 可匹配
  `b0-lkc123.abcde12345.us-east-1.aws.confluent.cloud`。
* 在一个 ClickHouse 服务的所有反向专用终结点中，名称必须唯一，
  包括通配符名称与精确名称之间重叠的情况。
* 使用保留后缀的名称 (例如 `local`、`localhost`、`internal`、`corp`、
  `private`) 将被拒绝。

要配置自定义私有 DNS name：

* 在 ClickHouse Cloud 控制台中，[创建反向专用终结点](#creating-clickpipe)时填写 `Custom private DNS name` 字段。为您的
  服务启用该功能后，此字段才会显示。
* 使用 [OpenAPI](https://clickhouse.com/docs/cloud/manage/api/swagger) 时，创建反向专用终结点时请设置
  `customPrivateDnsMappings`，或通过 `PATCH` 请求更新现有
  端点。更新会替换完整的映射列表；空列表
  会删除所有自定义名称。
* 使用 Terraform 时，使用
  [`clickhouse_clickpipes_reverse_private_endpoint_custom_private_dns`](https://registry.terraform.io/providers/ClickHouse/clickhouse/latest/docs/resources/clickpipes_reverse_private_endpoint_custom_private_dns)
  资源管理现有反向专用终结点的映射。

<div id="creating-clickpipe">
  ## 使用反向专用终结点创建 ClickPipe
</div>

1. 打开 ClickHouse Cloud 服务的 SQL 控制台。

<Image img="https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_service.webp?fit=max&auto=format&n=KW34O4k4cC0oxlHH&q=85&s=f0f46bfedc2978380d230af3ac7820b7" alt="ClickPipes 服务" size="md" border width="1184" height="482" data-path="images/integrations/data-ingestion/clickpipes/cp_service.webp" />

2. 在左侧菜单中选择 `Data Sources` 按钮，然后点击“设置 ClickPipe”。

<Image img="https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_step0.webp?fit=max&auto=format&n=KW34O4k4cC0oxlHH&q=85&s=9e134912809363f85f1602e2f744c872" alt="选择导入" size="lg" border width="2606" height="790" data-path="images/integrations/data-ingestion/clickpipes/cp_step0.webp" />

3. 选择 Kafka 或 Postgres 作为数据源。

<Image img="https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_rpe_select.webp?fit=max&auto=format&n=KW34O4k4cC0oxlHH&q=85&s=2b80025158ba39f6fd3c7464d172e050" alt="选择数据源" size="lg" border width="902" height="578" data-path="images/integrations/data-ingestion/clickpipes/cp_rpe_select.webp" />

4. 选择 `Reverse private endpoint` 选项。

<Image img="https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_rpe_step0.webp?fit=max&auto=format&n=KW34O4k4cC0oxlHH&q=85&s=48185a61c3c3724530de4b8bc94a6019" alt="选择反向专用终结点" size="lg" border width="882" height="875" data-path="images/integrations/data-ingestion/clickpipes/cp_rpe_step0.webp" />

5. 选择现有的任一反向专用终结点，或创建新的终结点。

<Info>
  如果 RDS 需要跨区域访问，则需要创建 VPC endpoint service，
  [本指南](/docs/zh/resources/support-center/knowledge-base/cloud-services/aws-privatelink-setup-for-clickpipes)可作为设置的良好起点。

  对于同一区域访问，建议创建 VPC 资源。
</Info>

<Image img="https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_rpe_step1.webp?fit=max&auto=format&n=KW34O4k4cC0oxlHH&q=85&s=d36ffe50a3ff440c2a3fcbb232dffe02" alt="选择反向专用终结点" size="lg" border width="811" height="232" data-path="images/integrations/data-ingestion/clickpipes/cp_rpe_step1.webp" />

6. 为所选端点类型提供必需参数。

<Image img="https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_rpe_step2.webp?fit=max&auto=format&n=KW34O4k4cC0oxlHH&q=85&s=33223b0fe4dfdae41fffee7966c4cd09" alt="选择反向专用终结点" size="lg" border width="1445" height="968" data-path="images/integrations/data-ingestion/clickpipes/cp_rpe_step2.webp" />

* 对于 VPC 资源，请提供配置共享 ARN 和配置 ID。
  * 对于 MSK multi-VPC，请提供集群 ARN，以及已创建端点使用的身份验证方法。
  * 对于 VPC endpoint service，请提供服务名称。
  * 也可以选择提供[自定义私有 DNS](#custom-private-dns) 名称。

7. 点击 `Create`，然后等待反向专用终结点就绪。

   如果要创建新的终结点，设置过程需要一些时间。
   终结点就绪后，页面将自动刷新。
   对于 VPC endpoint service，您可能需要在 AWS 控制台中接受连接请求。

<Image img="https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_rpe_step3.webp?fit=max&auto=format&n=KW34O4k4cC0oxlHH&q=85&s=9e2ceed680e979dfe90dd209fc7a570e" alt="选择反向专用终结点" size="lg" border width="1068" height="1022" data-path="images/integrations/data-ingestion/clickpipes/cp_rpe_step3.webp" />

8. 终结点就绪后，您可以使用 DNS name 连接到数据源。

   在端点列表中，您可以查看可用端点的 DNS name。
   它可以是 ClickPipes 在内部预配的 DNS name、PrivateLink 服务提供的私有 DNS 名称，
   或[自定义私有 DNS 名称](#custom-private-dns)。
   DNS name 不是完整的网络地址。
   请根据数据源添加端口。

   可在 AWS 控制台中获取 MSK connection string。

   要查看完整的 DNS name 列表，请前往 Cloud 服务设置。

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

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

1. 在侧边栏中找到并点击 `Settings` 按钮。

   <Image img="https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_rpe_settings0.webp?fit=max&auto=format&n=KW34O4k4cC0oxlHH&q=85&s=71e42e9eea9482ef95a7a0268daed9e2" alt="ClickHouse Cloud 设置" size="lg" border width="1120" height="928" data-path="images/integrations/data-ingestion/clickpipes/cp_rpe_settings0.webp" />

2. 在 `ClickPipe reverse private endpoints` 部分中，点击 `Reverse private endpoints`。

   <Image img="https://mintcdn.com/private-7c7dfe99/KW34O4k4cC0oxlHH/images/integrations/data-ingestion/clickpipes/cp_rpe_settings1.webp?fit=max&auto=format&n=KW34O4k4cC0oxlHH&q=85&s=085af9a759cfaa002abb814936c14600" alt="ClickHouse Cloud 设置" size="md" border width="579" height="705" data-path="images/integrations/data-ingestion/clickpipes/cp_rpe_settings1.webp" />

   弹出面板中会显示反向专用终结点的详细信息。

   端点创建后无法编辑。您可以点击端点上的 `×` 并确认删除。删除操作不可恢复，并会中断所有当前使用该端点的 ClickPipe。

<div id="aws-privatelink-regions">
  ## 支持的 AWS 区域
</div>

ClickPipes 对 AWS PrivateLink 的支持仅限于特定 AWS 区域。
请参阅 [ClickPipes 区域列表](/docs/zh/integrations/clickpipes/networking/static-ips)，查看可用区域。

启用了跨区域连接的 PrivateLink VPC endpoint service 不受此限制。

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

无法保证在 ClickHouse Cloud 中为 ClickPipes 创建的 AWS PrivateLink 端点
与 ClickHouse Cloud 服务位于同一 AWS 区域。

目前，只有 VPC endpoint service 支持
跨区域连接。

专用端点关联到特定的 ClickHouse 服务，无法在不同服务之间转移。
同一 ClickHouse 服务的多个 ClickPipes 可以复用同一端点。

对于每个 MSK 集群的每种身份验证类型 (SASL\_IAM 或 SASL\_SCRAM) ，AWS MSK 仅支持一个 PrivateLink (VPC 端点) 。因此，多个 ClickHouse Cloud 服务或组织无法使用相同的身份验证类型为同一 MSK 集群分别创建 PrivateLink 连接。

<div id="automatic-cleanup">
  ### 非活动端点的自动清理
</div>

处于终止状态的反向专用终结点会在规定的宽限期后自动删除。
这可确保未使用或配置不当的端点不会被无限期保留。

根据端点状态，适用以下宽限期：

| 状态      | 宽限期 | 描述             |
| ------- | --- | -------------- |
| **失败**  | 7 天 | 端点在预配过程中遇到错误。  |
| **待接受** | 1 天 | 服务所有者尚未接受端点连接。 |
| **已拒绝** | 1 天 | 服务所有者已拒绝端点连接。  |
| **已过期** | 立即  | 端点已过期，将被立即删除。  |

宽限期届满后，端点及其所有相关资源将被自动删除。

要避免被自动删除，请在宽限期届满前解决根本问题。
例如，在 AWS 控制台中接受待处理的连接请求，
或者在端点进入失败状态后重新创建端点。