configuring-private-connectivity

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Configuring Private Connectivity

配置私有连接

Configures private network connectivity for CockroachDB Cloud clusters to eliminate public internet exposure for database traffic. Covers ingress private endpoints (AWS PrivateLink, GCP Private Service Connect, Azure Private Link), egress private endpoints for outbound connections to external services, and VPC peering.

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

When to Use This Skill

适用场景

Setting up private endpoints to eliminate public internet exposure for database connections
Configuring egress private endpoints for CDC changefeeds to Confluent Kafka or other external services
Establishing VPC peering between a CockroachDB Cloud cluster and application VPCs
Troubleshooting DNS resolution issues with private endpoints
Resolving "stuck pending" or connection failure errors with private endpoints
Automating private connectivity setup with Terraform

设置私有端点，消除数据库连接的公网暴露
配置出口私有端点，用于将CDC变更馈送连接至Confluent Kafka或其他外部服务
在CockroachDB Cloud集群与应用VPC之间建立VPC对等连接
排查私有端点的DNS解析问题
解决私有端点的“停滞待处理”或连接失败错误
使用Terraform自动化私有连接设置

Prerequisites

前提条件

CockroachDB Cloud cluster — Standard or Advanced plan (VPC peering requires Advanced)
ccloud CLI authenticated with Cluster Admin role
Cloud provider access:
- AWS: IAM permissions to create VPC endpoints, modify DNS, and manage security groups
- GCP: Permissions to create Private Service Connect endpoints and DNS records
- Azure: Permissions to create private endpoints and manage DNS zones
Cluster ID and cloud provider details from
```
ccloud cluster info
```

Verify access:

bash

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

See ccloud commands reference for full command syntax.

CockroachDB Cloud集群 — 标准或高级套餐（VPC对等连接需要高级套餐）
ccloud CLI 已通过Cluster Admin角色认证
云提供商权限：
- AWS： 具备创建VPC端点、修改DNS和管理安全组的IAM权限
- GCP： 具备创建Private Service Connect端点和DNS记录的权限
- Azure： 具备创建私有端点和管理DNS区域的权限
从
```
ccloud cluster info
```
获取的集群ID和云提供商详情

验证权限：

bash

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

查看ccloud命令参考获取完整命令语法。

Configuration Decisions

配置决策

Before proceeding, determine which connectivity types and cloud provider apply to the user's environment. Ask which options are relevant, then follow only the corresponding sections below.

Decision 1 — Connectivity type(s) needed:

Ingress private endpoints: Applications connect to CockroachDB over a private network path (AWS PrivateLink, GCP Private Service Connect, Azure Private Link). Most common use case.
Egress private endpoints: CockroachDB connects outbound to external services (e.g., Confluent Kafka for CDC) over a private path.
VPC peering: Direct network connection between the application VPC and the CockroachDB Cloud VPC. Requires Advanced plan.
Combination: Multiple connectivity types can be configured together.

Decision 2 — Cloud provider:

AWS: Use AWS PrivateLink for ingress, AWS VPC peering for peering.
GCP: Use GCP Private Service Connect for ingress, GCP VPC peering for peering.
Azure: Use Azure Private Link for ingress. VPC peering is not available for Azure.

开始操作前，请确定适用于用户环境的连接类型和云提供商。询问用户相关选项，然后仅遵循下方对应的章节。

决策1 — 需要的连接类型：

入口私有端点： 应用通过私有网络路径连接至CockroachDB（AWS PrivateLink、GCP Private Service Connect、Azure Private Link）。最常见的使用场景。
出口私有端点： CockroachDB通过私有路径向外连接至外部服务（例如，用于CDC的Confluent Kafka）。
VPC对等连接： 应用VPC与CockroachDB Cloud VPC之间的直接网络连接。需要高级套餐。
组合配置： 可同时配置多种连接类型。

决策2 — 云提供商：

AWS： 使用AWS PrivateLink作为入口连接，使用AWS VPC对等连接实现对等。
GCP： 使用GCP Private Service Connect作为入口连接，使用GCP VPC对等连接实现对等。
Azure： 使用Azure Private Link作为入口连接。Azure不支持VPC对等连接。

Steps

操作步骤

Part 1: Ingress Private Endpoints

第一部分：入口私有端点

Follow this part only if the user selected Ingress private endpoints in Decision 1. Follow only the subsection (1.2, 1.3, or 1.4) matching the user's cloud provider from Decision 2.

Private endpoints allow applications in your VPC to connect to CockroachDB Cloud without traversing the public internet.

仅当用户在决策1中选择入口私有端点时遵循此部分。仅遵循与决策2中用户云提供商匹配的子章节（1.2、1.3或1.4）。

私有端点允许您VPC中的应用无需经过公网即可连接至CockroachDB Cloud。

1.1 Get the Private Endpoint Service

1.1 获取私有端点服务信息

Get the private endpoint service information from the Cloud Console or Cloud API:

Cloud Console: Navigate to your cluster's Networking > Private endpoint tab. The service name/ID is displayed.

Cloud API:

bash

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

This returns the cloud provider service name/ID needed to create the endpoint in your cloud account.

从云控制台或云API获取私有端点服务信息：

云控制台： 导航至集群的网络 > 私有端点标签页。将显示服务名称/ID。

云API：

bash

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

此命令将返回在您的云账户中创建端点所需的云提供商服务名称/ID。

1.2 Create the Private Endpoint (AWS PrivateLink)

1.2 创建私有端点（AWS PrivateLink）

bash

undefined

bash

undefined

In your AWS account, create a VPC endpoint

在您的AWS账户中，创建VPC端点

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>


**Security group requirements:**
- Allow inbound TCP port 26257 from your application subnets
- Allow outbound to the VPC endpoint


**安全组要求：**
- 允许来自您应用子网的入站TCP端口26257
- 允许出站至VPC端点

1.3 Create the Private Endpoint (GCP Private Service Connect)

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

bash

undefined

bash

undefined

Reserve an internal IP address

保留内部IP地址

gcloud compute addresses create cockroachdb-psc
--region=<region>
--subnet=<subnet>
--addresses=<internal-ip>

Create the Private Service Connect endpoint

创建Private Service Connect端点

gcloud compute forwarding-rules create cockroachdb-psc
--region=<region>
--network=<network>
--address=cockroachdb-psc
--target-service-attachment=<service-attachment-from-ccloud>

undefined

gcloud compute forwarding-rules create cockroachdb-psc
--region=<region>
--network=<network>
--address=cockroachdb-psc
--target-service-attachment=<service-attachment-from-ccloud>

undefined

1.4 Create the Private Endpoint (Azure Private Link)

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

bash

undefined

bash

undefined

Create a private endpoint in your Azure subscription

在您的Azure订阅中创建私有端点

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

undefined

undefined

1.5 Register the Endpoint in CockroachDB Cloud

1.5 在CockroachDB Cloud中注册端点

Cloud Console: Navigate to your cluster's Networking > Private endpoint tab, click Add a private endpoint, and enter the cloud provider endpoint ID.

Cloud API:

bash

undefined

通过云控制台或云API注册私有端点：

云控制台： 导航至集群的网络 > 私有端点标签页，点击添加私有端点，并输入云提供商端点ID。

云API：

bash

undefined

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:**
```hcl
resource "cockroach_private_endpoint_connection" "connection" {
  cluster_id  = cockroach_cluster.cluster.id
  endpoint_id = "<cloud-provider-endpoint-id>"
}

Wait for the connection status to become

AVAILABLE

— check in the Cloud Console or via API:

bash

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


**Terraform：**
```hcl
resource "cockroach_private_endpoint_connection" "connection" {
  cluster_id  = cockroach_cluster.cluster.id
  endpoint_id = "<cloud-provider-endpoint-id>"
}

等待连接状态变为

AVAILABLE

— 在云控制台或通过API检查：

bash

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

1.6 Configure DNS

1.6 配置DNS

Private endpoints require DNS configuration so clients resolve the cluster hostname to the private endpoint IP instead of the public IP.

AWS: Create a Route 53 private hosted zone with the cluster hostname pointing to the VPC endpoint DNS name.

GCP: Create a Cloud DNS private zone with an A record pointing to the reserved internal IP.

Azure: Create a private DNS zone with an A record pointing to the private endpoint IP.

See cloud provider setup reference for detailed DNS configuration steps.

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

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

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

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

查看云提供商设置参考获取详细DNS配置步骤。

Part 2: Egress Private Endpoints

第二部分：出口私有端点

Skip this part if the user did not select Egress private endpoints in Decision 1.

Egress private endpoints allow CockroachDB Cloud to connect to external services (e.g., Confluent Kafka for CDC) over a private network path.

如果用户在决策1中未选择出口私有端点，请跳过此部分。

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

2.1 Create an Egress Private Endpoint

2.1 创建出口私有端点

Create an egress endpoint via the Cloud Console or Cloud API:

Cloud Console: Navigate to your cluster's Networking > Egress tab, click Add egress endpoint, and specify the external service.

Cloud API:

bash

undefined

通过云控制台或云API创建出口端点：

云控制台： 导航至集群的网络 > 出口标签页，点击添加出口端点，并指定外部服务。

云API：

bash

undefined

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>"}'


**Common egress targets:**
- Confluent Cloud Kafka (most common use case)
- Amazon MSK
- Self-managed Kafka on PrivateLink
- Other SaaS services with PrivateLink support


**常见出口目标：**
- Confluent Cloud Kafka（最常见的使用场景）
- Amazon MSK
- 基于PrivateLink的自托管Kafka
- 其他支持PrivateLink的SaaS服务

2.2 Accept the Endpoint Connection

2.2 接受端点连接

The external service owner must accept the pending connection request. For Confluent Cloud:

Log into Confluent Cloud Console
Navigate to Networking > Private Link Access
Accept the pending connection from the CockroachDB Cloud account

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

登录Confluent Cloud控制台
导航至网络 > Private Link访问
接受来自CockroachDB Cloud账户的待处理连接

2.3 Verify Egress Endpoint Status

2.3 验证出口端点状态

Check egress endpoint status via the Cloud Console (Networking > Egress tab) or Cloud API:

bash

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

Troubleshooting "stuck pending":

Verify the external service has accepted the connection
Check that the external service is in the same cloud provider region
Contact the external service admin to accept the pending connection

通过云控制台（网络 > 出口标签页）或云API检查出口端点状态：

bash

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

排查“停滞待处理”问题：

验证外部服务已接受连接
检查外部服务是否与集群位于同一云提供商区域
联系外部服务管理员接受待处理连接

2.4 Use the Egress Endpoint in CDC Changefeeds

2.4 在CDC变更馈送中使用出口端点

sql

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

sql

-- 使用出口端点创建变更馈送
CREATE CHANGEFEED FOR TABLE orders
  INTO 'kafka://<private-kafka-endpoint>:9092?topic_prefix=crdb_'
  WITH updated, resolved;

Part 3: VPC Peering

第三部分：VPC对等连接

Skip this part if the user did not select VPC peering in Decision 1. Follow only the commands matching the user's cloud provider (AWS or GCP) from Decision 2. Azure does not support VPC peering.

VPC peering creates a direct network connection between your VPC and the CockroachDB Cloud VPC.

如果用户在决策1中未选择VPC对等连接，请跳过此部分。仅遵循与决策2中用户云提供商（AWS或GCP）匹配的命令。Azure不支持VPC对等连接。

VPC对等连接在您的VPC与CockroachDB Cloud VPC之间创建直接网络连接。

3.1 Initiate VPC Peering

3.1 发起VPC对等连接

bash

undefined

bash

undefined

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>

undefined

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

undefined

3.2 Accept the Peering Request

3.2 接受对等连接请求

AWS: Accept the peering request in the VPC Console:

bash

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

GCP: Peering is established automatically if the peer network configuration is correct.

AWS： 在VPC控制台中接受对等连接请求：

bash

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

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

3.3 Configure Route Tables

3.3 配置路由表

After peering is established, update route tables to route traffic to the CockroachDB Cloud CIDR through the peering connection.

bash

undefined

对等连接建立后，更新路由表，将前往CockroachDB Cloud CIDR的流量通过对等连接路由。

bash

undefined

AWS — add a route to the CockroachDB Cloud CIDR

AWS — 添加前往CockroachDB Cloud CIDR的路由

aws ec2 create-route
--route-table-id <route-table-id>
--destination-cidr-block <cockroachdb-cidr>
--vpc-peering-connection-id <peering-id>

undefined

aws ec2 create-route
--route-table-id <route-table-id>
--destination-cidr-block <cockroachdb-cidr>
--vpc-peering-connection-id <peering-id>

undefined

3.4 Verify VPC Peering

3.4 验证VPC对等连接

bash

undefined

bash

undefined

Check peering status

检查对等连接状态

ccloud cluster networking peering list <cluster-id> -o json


Test connectivity from your VPC:
```bash

ccloud cluster networking peering list <cluster-id> -o json


从您的VPC测试连接：
```bash

From an instance in your peered VPC

从对等VPC中的实例执行

cockroach sql --url "<connection-string>" -e "SELECT 1;"

undefined

cockroach sql --url "<connection-string>" -e "SELECT 1;"

undefined

Safety Considerations

安全注意事项

Impact Type	Severity	Recommendation
Private endpoint creation	Low	Does not affect existing connections; additive change
DNS configuration change	Medium	Incorrect DNS can break existing connections
IP allowlist interaction	Medium	Private endpoints bypass IP allowlists; review security implications
VPC peering CIDR overlap	High	Overlapping CIDRs will prevent peering; plan IP space carefully
Egress endpoint creation	Low	Does not affect cluster operation

Do not:

Delete a private endpoint that has active connections without migrating traffic first
Configure overlapping CIDR ranges between peered VPCs
Remove DNS records for private endpoints while clients are connected
Assume private endpoints replace all other security controls (authentication and authorization still apply)

When to prefer private endpoints over IP allowlists:

When the IP allowlist entry limit is insufficient for your number of source IPs
When you need to eliminate public internet exposure entirely
When compliance requirements mandate private network paths

影响类型	严重程度	建议
私有端点创建	低	不影响现有连接；属于增量变更
DNS配置变更	中	错误的DNS配置可能会中断现有连接
IP白名单交互	中	私有端点会绕过IP白名单；请审查安全影响
VPC对等连接CIDR重叠	高	重叠的CIDR会阻止对等连接；请仔细规划IP空间
出口端点创建	低	不影响集群运行

请勿：

在迁移流量前删除存在活跃连接的私有端点
在对等VPC之间配置重叠的CIDR范围
在客户端仍连接时删除私有端点的DNS记录
假设私有端点可替代所有其他安全控制（认证和授权仍然适用）

何时优先选择私有端点而非IP白名单：

当IP白名单条目数量不足以覆盖您的源IP数量时
当您需要完全消除公网暴露时
当合规要求强制使用私有网络路径时

Rollback

回滚操作

Remove a private endpoint:

bash

undefined

移除私有端点：

bash

undefined

Delete the endpoint connection in CockroachDB Cloud (via Cloud API)

在CockroachDB 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>


**Remove VPC peering:**
```bash
ccloud cluster networking peering delete <cluster-id> --peering-id <peering-id>

After removing private connectivity, ensure the IP allowlist is configured to allow connections from the public internet if needed.

aws ec2 delete-vpc-endpoints --vpc-endpoint-ids <endpoint-id>


**移除VPC对等连接：**
```bash
ccloud cluster networking peering delete <cluster-id> --peering-id <peering-id>

移除私有连接后，如果需要，请确保IP白名单已配置为允许来自公网的连接。

References

参考资料

Skill references:

ccloud networking commands
Cloud provider setup steps

Related skills:

configuring-ip-allowlists — IP-based network access control
auditing-cloud-cluster-security — Run a full security posture audit

Official CockroachDB Documentation:

技能参考：

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

相关技能：

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

官方CockroachDB文档：