AWS PrivateLink

Scale plan feature

AWS PrivateLink is available in the Scale and Enterprise plans. To upgrade, visit the plans page in the cloud console.

您可以使用 AWS PrivateLink 在不将流量暴露到公共 Internet 的情况下，在 VPC、AWS 服务、本地系统与 ClickHouse Cloud 之间建立安全连接。本文档概述了使用 AWS PrivateLink 连接到 ClickHouse Cloud 的步骤。

要将对 ClickHouse Cloud 服务的访问限制为仅能通过 AWS PrivateLink 地址进行，请按照 ClickHouse Cloud 提供的 IP Access Lists 指南进行配置。

注意

ClickHouse Cloud 在以下区域支持跨区域 PrivateLink：

sa-east-1
il-central-1
me-central-1
me-south-1
eu-central-2
eu-north-1
eu-south-2
eu-west-3
eu-south-1
eu-west-2
eu-west-1
eu-central-1
ca-west-1
ca-central-1
ap-northeast-1
ap-southeast-2
ap-southeast-1
ap-northeast-2
ap-northeast-3
ap-south-1
ap-southeast-4
ap-southeast-3
ap-south-2
ap-east-1
af-south-1
us-west-2
us-west-1
us-east-2
us-east-1 费用说明：AWS 会就跨区域数据传输向用户收费，定价请参见此处。

请完成以下步骤以启用 AWS PrivateLink：

获取 Endpoint 的 "Service name"。
创建 AWS Endpoint。
将 "Endpoint ID" 添加到 ClickHouse Cloud 组织。
将 "Endpoint ID" 添加到 ClickHouse 服务允许列表。

您可以在此处找到 Terraform 示例。

重要注意事项

ClickHouse 会尝试对您的服务进行分组，以便在同一 AWS 区域内复用同一个已发布的服务端点。但是，并不能保证一定会完成这种分组，尤其是在您将服务分散在多个 ClickHouse 组织中的情况下。

如果您已经在 ClickHouse 组织中为其他服务配置了 PrivateLink，那么通常可以跳过大部分步骤，直接进行最后一步：将 ClickHouse “Endpoint ID” 添加到 ClickHouse 服务允许列表中。

本流程的前提条件

在开始之前，需要准备：

AWS 账户。
具有在 ClickHouse 端创建和管理私有端点所需权限的 ClickHouse API key。

步骤

按照以下步骤，通过 AWS PrivateLink 连接您的 ClickHouse Cloud 服务。

获取端点的 “Service name”

选项 1：ClickHouse Cloud 控制台

在 ClickHouse Cloud 控制台中，打开您希望通过 PrivateLink 连接的服务，然后进入 Settings 菜单。

记下 Service name 和 DNS name，然后继续下一步。

选项 2：API

在运行任何命令之前，先设置以下环境变量：

REGION=<您的区域代码,使用 AWS 格式,例如:us-west-2>
PROVIDER=aws
KEY_ID=<您的 ClickHouse 密钥 ID>
KEY_SECRET=<您的 ClickHouse 密钥密文>
ORG_ID=<您的 ClickHouse 组织 ID>
SERVICE_NAME=<您的 ClickHouse 服务名称>

通过按区域、服务提供商和服务名称筛选来获取 ClickHouse INSTANCE_ID：

INSTANCE_ID=$(curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services" | \
jq ".result[] | select (.region==\"${REGION:?}\" and .provider==\"${PROVIDER:?}\" and .name==\"${SERVICE_NAME:?}\") | .id " -r)

获取用于 PrivateLink 配置的 endpointServiceId 和 privateDnsHostname：

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | \
jq .result

此命令应返回类似如下的输出：

{
  "endpointServiceId": "com.amazonaws.vpce.us-west-2.vpce-svc-xxxxxxxxxxxxxxxxx",
  "privateDnsHostname": "xxxxxxxxxx.us-west-2.vpce.aws.clickhouse.cloud"
}

记下 endpointServiceId 和 privateDnsHostname，然后继续下一步。

创建 AWS endpoint

参考资料

本节介绍通过 AWS PrivateLink 配置 ClickHouse 的特定细节。这里提供的 AWS 相关步骤仅作为参考，用于指引您到相应位置进行配置，但这些步骤可能会随 AWS 云服务提供商的变更而在未通知的情况下发生变化。请根据您的具体使用场景规划 AWS 配置。

请注意，ClickHouse 不负责为您配置所需的 AWS VPC endpoint、安全组规则或 DNS 记录。

如果您在设置 PrivateLink 时曾启用 “private DNS names”，并且现在在通过 PrivateLink 配置新服务时遇到问题，请联系 ClickHouse 支持。对于任何其他与 AWS 配置任务相关的问题，请直接联系 AWS Support。

选项 1：AWS 控制台

打开 AWS 控制台并前往 VPC → Endpoints → Create endpoints。

选择 Endpoint services that use NLBs and GWLBs，并在 Service Name 字段中使用您在 Obtain Endpoint "Service name" 步骤中获取的 Service name^console 或 endpointServiceId^API。单击 Verify service：

如果您希望通过 PrivateLink 建立跨区域连接，请启用 “Cross region endpoint” 复选框并指定服务区域。服务区域是 ClickHouse 实例运行所在的区域。

如果您收到 “Service name could not be verified.” 错误，请联系客户支持，申请将新区域添加到受支持区域列表。

接下来，选择您的 VPC 和子网：

可选步骤：分配 Security groups/Tags：

注意

确保在 security group 中放通端口 443、8443、9440、3306。

创建 VPC Endpoint 后，记下 Endpoint ID 的值；您将在后续步骤中用到它。

选项 2：AWS CloudFormation

接下来，需要使用在获取 Endpoint "Service name" 步骤中获得的 Service name^console 或 endpointServiceId^API 来创建 VPC Endpoint。请确保使用正确的子网 ID、安全组和 VPC ID。

Resources:
  ClickHouseInterfaceEndpoint:
    Type: 'AWS::EC2::VPCEndpoint'
    Properties:
      VpcEndpointType: Interface
      PrivateDnsEnabled: false
      ServiceName: <服务名称(endpointServiceId),请参阅上文>
      VpcId: vpc-vpc_id
      SubnetIds:
        - subnet-subnet_id1
        - subnet-subnet_id2
        - subnet-subnet_id3
      SecurityGroupIds:
        - sg-security_group_id1
        - sg-security_group_id2
        - sg-security_group_id3

创建 VPC Endpoint 后，记下 Endpoint ID 的值；你将在后续步骤中用到它。

选项 3：Terraform

下面的 service_name 指的是你在获取 Endpoint “Service name” 步骤中获得的 Service name^console 或 endpointServiceId^API

resource "aws_vpc_endpoint" "this" {
  vpc_id            = var.vpc_id
  service_name      = "<请参阅上方注释>"
  vpc_endpoint_type = "Interface"
  security_group_ids = [
    Var.security_group_id1,var.security_group_id2, var.security_group_id3,
  ]
  subnet_ids          = [var.subnet_id1,var.subnet_id2,var.subnet_id3]
  private_dns_enabled = false
  service_region      = "(可选)如果指定,VPC 端点将连接到指定区域中的服务。对于多区域 PrivateLink 连接,请定义此参数。"
}

在创建 VPC Endpoint 之后，请记下 Endpoint ID 的值；后续步骤中会用到。

为 Endpoint 设置私有 DNS 名称

注意

配置 DNS 有多种方式。请根据你的具体使用场景来设置 DNS。

你需要将在获取 Endpoint "Service name" 步骤中获得的 "DNS name" 指向 AWS Endpoint 的网络接口。这样可以确保 VPC/网络中的服务/组件能够正确解析它。

将 "Endpoint ID" 添加到 ClickHouse 服务允许列表

选项 1：通过 ClickHouse Cloud 控制台

要添加，请进入 ClickHouse Cloud 控制台，打开你希望通过 PrivateLink 连接的服务，然后进入 Settings。点击 Set up private endpoint 打开私有 endpoint 设置。输入在 Create AWS Endpoint 步骤中获取的 Endpoint ID，然后点击 "Create endpoint"。

注意

如果你希望允许来自现有 PrivateLink 连接的访问，请使用“现有 endpoint”下拉菜单。

要移除，请进入 ClickHouse Cloud 控制台，找到对应服务，然后进入该服务的 Settings，找到你想要移除的 endpoint，将其从 endpoint 列表中删除。

选项 2：通过 API

你需要将 Endpoint ID 添加到每个应通过 PrivateLink 访问的实例的允许列表中。

使用 Create AWS Endpoint 步骤中的数据设置 ENDPOINT_ID 环境变量。

在运行任何命令之前，先设置以下环境变量：

REGION=<您的区域代码,使用 AWS 格式,例如:us-west-2>
PROVIDER=aws
KEY_ID=<您的 ClickHouse 密钥 ID>
KEY_SECRET=<您的 ClickHouse 密钥>
ORG_ID=<您的 ClickHouse 组织 ID>
SERVICE_NAME=<您的 ClickHouse 服务名称>

若要将 endpoint ID 添加到允许列表：

cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "add": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
-X PATCH -H "Content-Type: application/json" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" \
-d @pl_config.json | jq

要从允许列表中移除某个端点 ID：

cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "remove": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
-X PATCH -H "Content-Type: application/json" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" \
-d @pl_config.json | jq

使用 PrivateLink 访问实例

每个启用了 Private Link 的服务都有一个公共端点和一个私有端点。要通过 Private Link 进行连接，需要使用私有端点，该端点对应从 Obtain Endpoint "Service name" 获取的 privateDnsHostname^API 或 DNS Name^console。

获取私有 DNS 主机名

选项 1：ClickHouse Cloud 控制台

在 ClickHouse Cloud 控制台中，进入 Settings。点击 Set up private endpoint 按钮。在弹出的侧边面板中，复制 DNS Name。

选项 2：API

在运行任何命令之前，先设置以下环境变量：

KEY_ID=<您的 ClickHouse 密钥 ID>
KEY_SECRET=<您的 ClickHouse 密钥密文>
ORG_ID=<您的 ClickHouse 组织 ID>
INSTANCE_ID=<您的 ClickHouse 服务名称>

可在步骤中获取 INSTANCE_ID。

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | \
jq .result

这将输出类似如下的结果：

{
  "endpointServiceId": "com.amazonaws.vpce.us-west-2.vpce-svc-xxxxxxxxxxxxxxxxx",
  "privateDnsHostname": "xxxxxxxxxx.us-west-2.vpce.aws.clickhouse.cloud"
}

在此示例中，使用 privateDnsHostname 主机名发起的连接将通过 PrivateLink 路由，而使用 endpointServiceId 主机名发起的连接将通过 Internet 路由。

故障排查

在同一区域中使用多个 PrivateLink

在大多数情况下，你只需要为每个 VPC 创建一个终端节点服务（endpoint service）。该终端节点可以将来自该 VPC 的请求路由到多个 ClickHouse Cloud 服务。
请参见此处

连接到私有终端节点超时

请将安全组（security group）关联到 VPC Endpoint。
请检查关联到该 Endpoint 的安全组中的 inbound 规则，并放通 ClickHouse 使用的端口。
请检查用于连通性测试的 VM 所关联安全组中的 outbound 规则，并放通到 ClickHouse 端口的连接。

私有主机名：未找到主机地址

请检查你的 DNS 配置

连接被对端重置（Connection reset by peer）

很可能是 Endpoint ID 尚未添加到服务允许列表（allow list），请访问此步骤

检查 endpoint 过滤条件

在运行任何命令之前，请先设置以下环境变量：

KEY_ID=<密钥 ID>
KEY_SECRET=<密钥密文>
ORG_ID=<请设置 ClickHouse 组织 ID>
INSTANCE_ID=<实例 ID>

你可以在此步骤中获取 INSTANCE_ID。

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
-X GET -H "Content-Type: application/json" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" | \
jq .result.privateEndpointIds

连接到远程数据库

假设你尝试在 ClickHouse Cloud 中使用 MySQL 或 PostgreSQL 表函数，并连接到托管在 Amazon Web Services (AWS) VPC 中的数据库。AWS PrivateLink 无法用于在保证安全的前提下建立此连接。PrivateLink 是一种单向连接。它允许你的内部网络或 Amazon VPC 安全地连接到 ClickHouse Cloud，但不允许 ClickHouse Cloud 连接到你的内部网络。

根据 AWS PrivateLink 文档所述：

当你采用客户端/服务器架构，并希望允许一个或多个服务使用方 VPC 对服务提供方 VPC 中的特定服务或一组实例进行单向访问时，请使用 AWS PrivateLink。只有服务使用方 VPC 中的客户端可以向服务提供方 VPC 中的服务发起连接。

要实现这一点，请配置你的 AWS Security Groups，允许从 ClickHouse Cloud 到你的内部/私有数据库服务的连接。查看 ClickHouse Cloud 各区域的默认出站 IP 地址，以及可用的静态 IP 地址。

重要注意事项​

本流程的前提条件​

步骤​

获取端点的 “Service name”​

选项 1：ClickHouse Cloud 控制台​

选项 2：API​

创建 AWS endpoint​

选项 1：AWS 控制台​

选项 2：AWS CloudFormation​

选项 3：Terraform​

为 Endpoint 设置私有 DNS 名称​

将 "Endpoint ID" 添加到 ClickHouse 服务允许列表​

选项 1：通过 ClickHouse Cloud 控制台​

选项 2：通过 API​

使用 PrivateLink 访问实例​

获取私有 DNS 主机名​

选项 1：ClickHouse Cloud 控制台​

选项 2：API​

故障排查​

在同一区域中使用多个 PrivateLink​

连接到私有终端节点超时​

私有主机名：未找到主机地址​

连接被对端重置（Connection reset by peer）​

检查 endpoint 过滤条件​

连接到远程数据库​

重要注意事项

本流程的前提条件

步骤

获取端点的 “Service name”

选项 1：ClickHouse Cloud 控制台

选项 2：API

创建 AWS endpoint

选项 1：AWS 控制台

选项 2：AWS CloudFormation

选项 3：Terraform

为 Endpoint 设置私有 DNS 名称

将 "Endpoint ID" 添加到 ClickHouse 服务允许列表

选项 1：通过 ClickHouse Cloud 控制台

选项 2：通过 API

使用 PrivateLink 访问实例

获取私有 DNS 主机名

选项 1：ClickHouse Cloud 控制台

选项 2：API

故障排查

在同一区域中使用多个 PrivateLink

连接到私有终端节点超时

私有主机名：未找到主机地址

连接被对端重置（Connection reset by peer）

检查 endpoint 过滤条件

连接到远程数据库