configuring-private-connectivity（配置专用连接）

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.

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

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:

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

See ccloud commands reference for full command syntax.

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.

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.1 Get the Private Endpoint Service

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:

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.

1.2 Create the Private Endpoint (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>

Security group requirements:

• Allow inbound TCP port 26257 from your application subnets
• Allow outbound to the VPC endpoint

1.3 Create the Private Endpoint (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 Create the Private Endpoint (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 Register the Endpoint in CockroachDB Cloud

Register the private endpoint via the Cloud Console or Cloud API:

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:

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

Wait for the connection status to become AVAILABLE — check in the Cloud Console or via API:

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

1.6 Configure 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.

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.

2.1 Create an Egress Private Endpoint

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:

# 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

2.2 Accept the Endpoint Connection

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

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

2.3 Verify Egress Endpoint Status

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

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

2.4 Use the Egress Endpoint in CDC Changefeeds

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

Part 3: VPC Peering

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.

3.1 Initiate VPC Peering

# 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 Accept the Peering Request

AWS: Accept the peering request in the VPC Console:

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

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

3.3 Configure Route Tables

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

# 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 Verify VPC Peering

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

Test connectivity from your VPC:

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

Safety Considerations

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

Rollback

Remove a private endpoint:

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

Remove VPC peering:

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.

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:

• Network Authorization
• AWS PrivateLink
• GCP Private Service Connect
• Azure Private Link
• VPC Peering
• Egress Perimeter Controls