AWS PrivateLink | ClickHouse Docs

Scale 计划功能

AWS PrivateLink 仅在 Scale 和 Enterprise 计划中可用。要升级，请访问 Cloud Console 中的计划页面。

您可以使用 AWS PrivateLink 在 VPC、AWS 服务、您的本地系统以及 ClickHouse Cloud 之间建立安全连接，而无需将流量暴露到公共互联网。本文档概述了通过 AWS PrivateLink 连接到 ClickHouse Cloud 的步骤。

若要将对您的 ClickHouse Cloud 服务的访问限制为仅可通过 AWS PrivateLink 地址进行，请按照 ClickHouse Cloud IP Access Lists 中提供的说明操作。

ClickHouse Cloud 支持为托管在以下 AWS 区域中的服务使用跨区域 PrivateLink：

该表仅涵盖服务托管区域。消费者接口 VPC 端点所在区域采用单独的允许列表；例如，尽管托管在 mx-central-1 的服务无法启用跨区域访问，mx-central-1 仍是允许的消费者区域。

区域代码	区域名称
`af-south-1`	非洲 (开普敦)
`ap-east-1`	亚太地区 (香港)
`ap-northeast-1`	亚太地区 (东京)
`ap-northeast-2`	亚太地区 (首尔)
`ap-south-1`	亚太地区 (孟买)
`ap-southeast-1`	亚太地区 (新加坡)
`ap-southeast-2`	亚太地区 (悉尼)
`ap-southeast-3`	亚太地区 (雅加达)
`ap-southeast-5`	亚太地区 (马来西亚)
`ca-central-1`	加拿大 (中部)
`eu-central-1`	欧洲 (法兰克福)
`eu-north-1`	欧洲 (斯德哥尔摩)
`eu-west-1`	欧洲 (爱尔兰)
`eu-west-2`	欧洲 (伦敦)
`il-central-1`	以色列 (特拉维夫)
`me-central-1`	中东 (阿联酋)
`sa-east-1`	南美洲 (圣保罗)
`us-east-1`	美国东部 (北弗吉尼亚)
`us-east-2`	美国东部 (俄亥俄)
`us-west-2`	美国西部 (俄勒冈)

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

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

可在此处找到 Terraform 示例。

重要注意事项

ClickHouse 会尝试将您的服务分组，以便在同一 AWS 区域内复用已发布的服务端点。不过，这种分组并不一定能保证，尤其是在您将服务分布到多个 ClickHouse organizations 中时。如果您所在的 ClickHouse organization 中的其他服务已经配置了 PrivateLink，通常就可以借助这种分组跳过大部分步骤，直接进入最后一步：将 ClickHouse “Endpoint ID” 添加到 ClickHouse 服务允许列表中。

此流程的前置条件

开始之前，您需要准备：

您的 AWS 账户。
具备在 ClickHouse 端创建和管理专用终结点所需权限的 ClickHouse API key。

步骤

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

获取端点“Service name”信息

选项 1：ClickHouse Cloud 控制台

在 ClickHouse Cloud 控制台中，打开要通过 PrivateLink 连接的服务，然后前往设置菜单。

记下 Service name 和 DNS name，然后进入下一步。

选项 2：API

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

REGION=<Your region code using the AWS format, for example: us-west-2>
PROVIDER=aws
KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
SERVICE_NAME=<Your ClickHouse service name>

按区域、提供商和服务名称筛选，以获取你的 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

选项 1：AWS 控制台

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

选择 Endpoint services that use NLBs and GWLBs，然后在 Service Name 字段中填入您在获取 Endpoint“Service name” 步骤中获得的 Service name^console 或 endpointServiceId^API。点击 Verify service：

如果出现 “Service name couldn't be verified.” 错误，请联系 Customer Support，申请将新区域添加到 supported regions 列表中。

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

作为可选步骤，分配安全组 (Security Group) /标签：

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

选项 2：AWS CloudFormation

接下来，您需要使用在获取端点“Service name”步骤中获得的 Service name^控制台或 endpointServiceId^API 创建 VPC 端点。请务必使用正确的子网 ID、安全组 (Security Group) 和 VPC ID。

Resources:
  ClickHouseInterfaceEndpoint:
    Type: 'AWS::EC2::VPCEndpoint'
    Properties:
      VpcEndpointType: Interface
      PrivateDnsEnabled: false
      ServiceName: <Service name(endpointServiceId), pls see above>
      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 ID 的值；后续步骤中会用到它。

选项 3：Terraform

下面的 service_name 是你在获取端点“Service name”信息步骤中获取到的 Service name^控制台或 endpointServiceId^API

resource "aws_vpc_endpoint" "this" {
  vpc_id            = var.vpc_id
  service_name      = "<pls see comment above>"
  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      = "(Optional) If specified, the VPC endpoint will connect to the service in the provided region. Define it for multi-regional PrivateLink connections."
}

创建 VPC 端点后，请记下 Endpoint ID 的值；后续步骤会用到它。

为端点设置私有 DNS 名称

你需要将获取端点“Service name”步骤中获取的“DNS name”指向 AWS endpoint 网络接口。这样可确保你的 VPC/网络中的服务/组件能够正确解析该名称。

将“Endpoint ID”添加到 ClickHouse 服务的允许列表中

选项 1：ClickHouse Cloud 控制台

如需添加，请前往 ClickHouse Cloud 控制台，打开要通过 PrivateLink 连接的服务，然后进入设置。点击 Set up private endpoint 打开专用终结点设置。输入在创建 AWS endpoint步骤中获取的 Endpoint ID。点击“Create endpoint”。

如需移除，请前往 ClickHouse Cloud 控制台，找到相应服务，然后进入该服务的设置，找到要移除的端点，并将其从端点列表中删除。

选项 2：API

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

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

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

REGION=<您的区域代码，使用 AWS 格式，例如：us-west-2>
PROVIDER=aws
KEY_ID=<您的 ClickHouse 密钥 ID>
KEY_SECRET=<您的 ClickHouse 密钥 secret>
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

要从允许列表中删除某个 Endpoint 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 进行连接，您需要使用专用端点，即获取端点“Service name” 中的 privateDnsHostname^API 或 DNS Name^控制台。

获取私有 DNS 主机名

选项 1：ClickHouse Cloud 控制台

在 ClickHouse Cloud 控制台中，前往设置。点击 Set up private endpoint 按钮。在打开的弹出面板中，复制 DNS Name。

选项 2：API

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

KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
INSTANCE_ID=<Your ClickHouse service name>

你可以在步骤中获取 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 主机名建立的连接则会经由互联网路由。

故障排查

一个区域中的多个 PrivateLink

在大多数情况下，每个 VPC 只需创建一个终结点服务。该终结点可将请求从 VPC 路由到多个 ClickHouse Cloud 服务。请参阅此处

连接专用终结点超时

请将安全组 (Security Group) 关联到 VPC 端点。
请检查关联到端点的安全组 (Security Group) 的 inbound 规则，确保允许访问 ClickHouse 端口。
请检查关联到用于连接测试的 VM 的安全组 (Security Group) 的 outbound 规则，确保允许连接到 ClickHouse 端口。

私网主机名：找不到主机地址

请检查你的 DNS 配置

连接被对端重置

最可能的原因是 Endpoint ID 未添加到服务允许列表，请参阅步骤

检查端点过滤器

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

KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<please set ClickHouse organization ID>
INSTANCE_ID=<Instance 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

连接到远程数据库

根据 AWS PrivateLink 文档：

当你采用客户端/服务器架构，并希望允许一个或多个消费者 VPC 单向访问服务提供商 VPC 中的特定服务或一组实例时，请使用 AWS PrivateLink。只有消费者 VPC 中的客户端才能发起与服务提供商 VPC 中服务的连接。

要将 ClickHouse Cloud 中的 MySQL 或 PostgreSQL 表函数连接到托管在你的 AWS VPC 中的数据库，请配置你的 AWS 安全组，允许来自 ClickHouse Cloud 的连接。请查看 ClickHouse Cloud 各区域的默认出口 IP 地址以及可用的静态 IP 地址。