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:

bash

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:

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.

1.2 Create the Private Endpoint (AWS PrivateLink)

bash

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

bash

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

bash

# 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

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

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

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:

bash

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

Log into Confluent Cloud Console
Navigate to Networking > Private Link Access
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:

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

2.4 Use the Egress Endpoint in CDC Changefeeds

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;

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

bash

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

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.

3.3 Configure Route Tables

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

bash

# 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

bash

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

Test connectivity from your VPC:

bash

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

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

Rollback

Remove a private endpoint:

bash

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

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.

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:

configuring-private-connectivity

NPX Install

Tags

SKILL.md Content

Configuring Private Connectivity

When to Use This Skill

Prerequisites

Configuration Decisions

Steps

Part 1: Ingress Private Endpoints

1.1 Get the Private Endpoint Service

1.2 Create the Private Endpoint (AWS PrivateLink)

1.3 Create the Private Endpoint (GCP Private Service Connect)

1.4 Create the Private Endpoint (Azure Private Link)

1.5 Register the Endpoint in CockroachDB Cloud

1.6 Configure DNS

Part 2: Egress Private Endpoints

2.1 Create an Egress Private Endpoint

2.2 Accept the Endpoint Connection

2.3 Verify Egress Endpoint Status

2.4 Use the Egress Endpoint in CDC Changefeeds

Part 3: VPC Peering

3.1 Initiate VPC Peering

3.2 Accept the Peering Request

3.3 Configure Route Tables

3.4 Verify VPC Peering

Safety Considerations

Rollback

References