configuring-private-connectivity

配置私有连接

为 CockroachDB Cloud 集群配置私有网络连接，避免数据库流量暴露于公共互联网。涵盖入站私有端点（AWS PrivateLink、GCP Private Service Connect、Azure Private Link）、用于连接外部服务的出站私有端点，以及 VPC 对等连接。

何时使用此技能

• 设置私有端点，避免数据库连接暴露于公共互联网
• 配置用于 CDC 变更流的出站私有端点，以连接 Confluent Kafka 或其他外部服务
• 在 CockroachDB Cloud 集群与应用 VPC 之间建立 VPC 对等连接
• 排查私有端点的 DNS 解析问题
• 解决私有端点“卡在待处理状态”或连接失败错误
• 使用 Terraform 自动配置私有连接

前提条件

• CockroachDB Cloud 集群 — Standard 或 Advanced 计划（VPC 对等连接需要 Advanced 计划）
• 已通过 Cluster Admin 角色进行身份验证的 ccloud CLI
• 云服务提供商访问权限：
  • AWS： 创建 VPC 端点、修改 DNS 和管理安全组的 IAM 权限
  • GCP： 创建 Private Service Connect 端点和 DNS 记录的权限
  • Azure： 创建私有端点和管理 DNS 区域的权限
• 从 ccloud cluster info 获取的集群 ID 和云服务提供商详情

验证访问权限：

ccloud auth whoami
ccloud cluster info <cluster-name> -o json

完整命令语法请参阅 ccloud 命令参考。

配置决策

继续操作前，请确定用户环境适用的连接类型和云服务提供商。询问哪些选项适用，然后仅按照下方对应的部分操作。

决策 1 — 所需连接类型：

• 入站私有端点： 应用通过私有网络路径连接到 CockroachDB（AWS PrivateLink、GCP Private Service Connect、Azure Private Link）。这是最常见的用例。
• 出站私有端点： CockroachDB 通过私有路径向外连接外部服务（例如，用于 CDC 的 Confluent Kafka）。
• VPC 对等连接： 在应用 VPC 和 CockroachDB Cloud VPC 之间建立直接网络连接。需要 Advanced 计划。
• 组合： 可以同时配置多种连接类型。

决策 2 — 云服务提供商：

• AWS： 入站连接使用 AWS PrivateLink，对等连接使用 AWS VPC 对等连接。
• GCP： 入站连接使用 GCP Private Service Connect，对等连接使用 GCP VPC 对等连接。
• Azure： 入站连接使用 Azure Private Link。Azure 不支持 VPC 对等连接。

步骤

第 1 部分：入站私有端点

仅当用户在决策 1 中选择了入站私有端点时，才执行此部分。仅按照决策 2 中与用户云服务提供商相匹配的小节（1.2、1.3 或 1.4）操作。

私有端点允许 VPC 中的应用连接到 CockroachDB Cloud，而无需经过公共互联网。

1.1 获取私有端点服务

从 Cloud Console 或 Cloud API 获取私有端点服务信息：

Cloud Console： 导航到集群的 Networking > Private endpoint 选项卡。页面会显示服务名称／ID。

Cloud API：

curl "https://cockroachlabs.cloud/api/v1/clusters/<cluster-id>/networking/private-endpoint-services" \
  -H "Authorization: Bearer <api-key>"

此操作会返回在云账户中创建端点所需的云服务提供商服务名称／ID。

1.2 创建私有端点（AWS PrivateLink）

# In your AWS account, create a VPC endpoint
aws ec2 create-vpc-endpoint \
  --vpc-id <your-vpc-id> \
  --service-name <service-name-from-ccloud> \
  --vpc-endpoint-type Interface \
  --subnet-ids <subnet-id-1> <subnet-id-2> \
  --security-group-ids <security-group-id>

安全组要求：

• 允许来自应用子网的入站 TCP 端口 26257 流量
• 允许出站流量到 VPC 端点

1.3 创建私有端点（GCP Private Service Connect）

# Reserve an internal IP address
gcloud compute addresses create cockroachdb-psc \
  --region=<region> \
  --subnet=<subnet> \
  --addresses=<internal-ip>

# Create the Private Service Connect endpoint
gcloud compute forwarding-rules create cockroachdb-psc \
  --region=<region> \
  --network=<network> \
  --address=cockroachdb-psc \
  --target-service-attachment=<service-attachment-from-ccloud>

1.4 创建私有端点（Azure Private Link）

# Create a private endpoint in your Azure subscription
az network private-endpoint create \
  --name cockroachdb-pe \
  --resource-group <resource-group> \
  --vnet-name <vnet-name> \
  --subnet <subnet-name> \
  --private-connection-resource-id <service-id-from-ccloud> \
  --connection-name cockroachdb-connection

1.5 在 CockroachDB Cloud 中注册端点

通过 Cloud Console 或 Cloud API 注册私有端点：

Cloud Console： 前往集群的 Networking > Private endpoint 选项卡，点击 Add a private endpoint，然后输入云服务商端点 ID。

Cloud API：

# Register the private endpoint connection with the cluster
curl -X POST "https://cockroachlabs.cloud/api/v1/clusters/<cluster-id>/networking/private-endpoint-connections" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"endpoint_id": "<cloud-provider-endpoint-id>"}'

Terraform：

resource "cockroach_private_endpoint_connection" "connection" {
  cluster_id  = cockroach_cluster.cluster.id
  endpoint_id = "<cloud-provider-endpoint-id>"
}

等待连接状态变为 AVAILABLE — 在 Cloud Console 中或通过 API 检查：

curl "https://cockroachlabs.cloud/api/v1/clusters/<cluster-id>/networking/private-endpoint-connections" \
  -H "Authorization: Bearer <api-key>"

1.6 配置 DNS

私有端点需要配置 DNS，以便客户端将集群主机名解析为私有端点 IP，而不是公共 IP。

AWS： 创建 Route 53 私有托管区域，并将集群主机名指向 VPC 端点 DNS 名称。

GCP： 创建 Cloud DNS 私有区域，并添加指向预留内部 IP 的 A 记录。

Azure： 创建私有 DNS 区域，并添加指向私有端点 IP 的 A 记录。

详细的 DNS 配置步骤请参阅云服务商设置参考。

第 2 部分：出站私有端点

如果用户在决策 1 中未选择 Egress private endpoints，请跳过本部分。

出站私有端点允许 CockroachDB Cloud 通过私有网络路径连接到外部服务（例如，用于 CDC 的 Confluent Kafka）。

2.1 创建出站私有端点

通过 Cloud Console 或 Cloud API 创建出站端点：

Cloud Console： 前往集群的 Networking > Egress 选项卡，点击 Add egress endpoint，然后指定外部服务。

Cloud API：

# Create an egress endpoint to an external service
curl -X POST "https://cockroachlabs.cloud/api/v1/clusters/<cluster-id>/networking/egress-endpoints" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{"service_name": "<external-service-name>", "cloud_provider": "<AWS|GCP|AZURE>"}'

常见的出站目标：

• Confluent Cloud Kafka（最常见的用例）
• Amazon MSK
• 使用 PrivateLink 的自管理 Kafka
• 其他支持 PrivateLink 的 SaaS 服务

2.2 接受端点连接

外部服务所有者必须接受待处理的连接请求。对于 Confluent Cloud：

1. 登录 Confluent Cloud Console
2. 前往 Networking > Private Link Access
3. 接受来自 CockroachDB Cloud 账户的待处理连接

2.3 检查出站端点状态

在 Cloud Console（Networking > Egress 选项卡）中或通过 Cloud API 检查出站端点状态：

curl "https://cockroachlabs.cloud/api/v1/clusters/<cluster-id>/networking/egress-endpoints" \
  -H "Authorization: Bearer <api-key>"

排查“卡在待处理状态”的问题：

• 确认外部服务已接受连接
• 检查外部服务是否位于同一云服务商区域
• 联系外部服务管理员，接受待处理的连接

2.4 在 CDC Changefeed 中使用出站端点

-- Create a changefeed using the egress endpoint
CREATE CHANGEFEED FOR TABLE orders
  INTO 'kafka://<private-kafka-endpoint>:9092?topic_prefix=crdb_'
  WITH updated, resolved;

第 3 部分：VPC 对等连接

如果用户在决策 1 中未选择 VPC peering，请跳过本部分。根据决策 2，仅执行与用户云服务商（AWS 或 GCP）对应的命令。Azure 不支持 VPC 对等连接。

VPC 对等连接可在你的 VPC 与 CockroachDB Cloud VPC 之间建立直接网络连接。

3.1 发起 VPC 对等连接

# AWS
ccloud cluster networking peering create <cluster-id> \
  --peer-account-id <aws-account-id> \
  --peer-vpc-id <vpc-id> \
  --peer-vpc-region <region> \
  --peer-cidr <cidr-block>

# GCP
ccloud cluster networking peering create <cluster-id> \
  --peer-project-id <gcp-project-id> \
  --peer-network <network-name>

3.2 接受对等连接请求

AWS： 在 VPC Console 中接受对等连接请求：

aws ec2 accept-vpc-peering-connection \
  --vpc-peering-connection-id <peering-id>

GCP： 如果对等网络配置正确，对等连接会自动建立。

3.3 配置路由表

建立对等连接后，更新路由表，以便通过对等连接将流量路由到 CockroachDB Cloud CIDR。

# AWS — add a route to the CockroachDB Cloud CIDR
aws ec2 create-route \
  --route-table-id <route-table-id> \
  --destination-cidr-block <cockroachdb-cidr> \
  --vpc-peering-connection-id <peering-id>

3.4 验证 VPC 对等连接

# Check peering status
ccloud cluster networking peering list <cluster-id> -o json

从你的 VPC 测试连接：

# From an instance in your peered VPC
cockroach sql --url "<connection-string>" -e "SELECT 1;"

安全注意事项

影响类型	严重程度	建议
创建私有端点	低	不影响现有连接；属于增量变更
DNS 配置变更	中	DNS 配置错误可能导致现有连接中断
IP 允许列表交互	中	私有端点会绕过 IP 允许列表；请审查相关安全影响
VPC 对等连接 CIDR 重叠	高	CIDR 重叠会导致无法建立对等连接；请谨慎规划 IP 地址空间
创建出站端点	低	不影响集群运行

请勿：

• 在流量迁移前，删除仍有活动连接的私有端点
• 在建立对等连接的 VPC 之间配置重叠的 CIDR 范围
• 在客户端仍连接时，删除私有端点的 DNS 记录
• 假设私有端点可以取代所有其他安全控制（仍需进行身份验证和授权）

以下情况优先选择私有端点，而非 IP 允许列表：

• IP 允许列表条目数上限无法满足源 IP 数量需求时
• 需要彻底消除对公有互联网的暴露时
• 合规要求规定必须使用私有网络路径时

回滚

移除私有端点：

# Delete the endpoint connection in CockroachDB Cloud (via Cloud API)
curl -X DELETE "https://cockroachlabs.cloud/api/v1/clusters/<cluster-id>/networking/private-endpoint-connections/<endpoint-id>" \
  -H "Authorization: Bearer <api-key>"

# Or remove via Cloud Console: Networking > Private endpoint > Delete

# Then delete the endpoint in your cloud provider
# AWS
aws ec2 delete-vpc-endpoints --vpc-endpoint-ids <endpoint-id>

移除 VPC 对等连接：

ccloud cluster networking peering delete <cluster-id> --peering-id <peering-id>

移除私有连接后，如有需要，请确保已配置 IP 允许列表，以允许来自公有互联网的连接。

参考资料

技能参考：

• ccloud 网络命令
• 云服务提供商设置步骤

相关技能：

• configuring-ip-allowlists — 基于 IP 的网络访问控制
• auditing-cloud-cluster-security — 执行全面的安全态势审计

CockroachDB 官方文档：

• 网络授权
• AWS PrivateLink
• GCP Private Service Connect
• Azure Private Link
• VPC 对等连接
• 出站边界控制