Amazon Web Services (AWS) PrivateLink support allows customers to establish SQL access to their clusters entirely through private AWS infrastructure, without exposure to the public internet, affording enhanced security and performance. PrivateLink is supported for CockroachDB Dedicated clusters and multi-region CockroachDB Serverless clusters deployed on AWS.
For broader context, refer to Network Authorization for CockroachDB Cloud Clusters.
This page describes the steps to setting up an AWS PrivateLink connection for CockroachDB Dedicated and multi-region CockroachDB Serverless clusters from your AWS account.
AWS PrivateLink for CockroachDB Serverless is in limited access and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.
You must configure the AWS PrivateLink connection for your CockroachDB Dedicated cluster in CockroachDB Cloud and in AWS. For CockroachDB Cloud, you can use the CockroachDB Cloud Console, Cloud API or Terraform Provider. For help, refer to Establish VPC Peering or AWS PrivateLink.
If you have multiple clusters, you will have to repeat these steps for each cluster that you want to connect to using AWS PrivateLink.
You must configure the AWS PrivateLink connection for your CockroachDB Serverless cluster in CockroachDB Cloud and in AWS. For CockroachDB Cloud, you can use the CockroachDB Cloud Console, Cloud API or Terraform Provider. For help, refer to Establish AWS PrivateLink.
If you have multiple clusters, you will have to repeat these steps for each cluster that you want to connect to using AWS PrivateLink.
Step 1. Set up a cluster
Use the CockroachDB Cloud Console to create your CockroachDB Dedicated cluster on AWS in the same region as your application.
Note:If you have a multi-region cluster, you will have to create a PrivateLink connection for each region you are operating in.
Navigate to the Networking page.
Select the PrivateLink tab.
Click Add Connection to open the connection dialog.
Continue to Step 3. Create an AWS endpoint.
Use the CockroachDB Cloud Console to create a multi-region CockroachDB Serverless cluster on AWS in the same regions as your application.
Navigate to the Networking page.
Select the PrivateLink tab. PrivateLink connections that have already been configured are shown as a private endpoint allowlist.
To add a new private connection, click Add Connection to open the connection dialog.
Continue to Step 3. Create an AWS endpoint.
Step 2. (Optional) Configure private endpoint trusted owners
This feature is in limited access and is only available to enrolled organizations. To enroll your organization, contact your Cockroach Labs account team. This feature is subject to change.
Optionally, you can restrict the AWS accounts that can connect to your cluster privately using private endpoints. During Limited Access, to configure trusted owners, you must use the CockroachDB Cloud API or Terraform Provider.
Keep the following in mind:
- This feature can be enabled only on clusters created after your organization is enrolled in the Limited Access.
- After your organization is enrolled, an attempt to configure a private endpoint from an AWS account that has not been added as a trusted owner will fail.
- After your organization is enrolled in the Limited Access, the feature cannot be disabled.
Your service account must have one of the following roles on the cluster, either directly or by inheritance:
- Cluster Administrator to add or remove private endpoint trusted owners. The Cluster Administrator role includes all of the capabilities of the Cluster Operator role.
- Cluster Operator to list or get details about private endpoint trusted owners.
Add a private endpoint trusted owner
To add a private endpoint trusted owner:
curl --request POST \
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-trusted-owners \
--header 'Authorization: Bearer {bearer_token' \
--header 'content-type: application/json' \
--data '{"external_owner_id":"{aws_account_id}","type":"AWS_ACCOUNT_ID"}'
Replace:
{cluster_id}: The ID of the cluster.{bearer_token}: The service account's API key.{aws_account_id}: The ID of the AWS account to trust.
The response includes details about the trusted owner, including a unique trusted owner ID. This ID is required to get details about or remove a trusted owner.
Next, you can create an AWS endpoint.
List private endpoint trusted owners
To list private endpoint trusted owners for a cluster:
curl --request GET \
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-trusted-owners \
--header 'Authorization: Bearer {bearer_token}'
Replace:
{cluster_id}: The ID of the cluster.{bearer_token}: The service account's API key.
Get details about a trusted owner
To get details about a private endpoint trusted owner:
curl --request GET \
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-trusted-owners/{owner_id} \
--header 'Authorization: Bearer {bearer_token}'
Replace:
{cluster_id}: The ID of the cluster.{owner_id}: The UUID of a private endpoint trusted owner entry.{bearer_token}: The service account's API key.
Remove a trusted owner
To remove a private endpoint trusted owner:
curl --request DELETE \
--url https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/networking/private-endpoint-trusted-owners/{owner_id} \
--header 'Authorization: {bearer_token}'
Replace:
{cluster_id}: The ID of the cluster.{owner_id}: The UUID of a private endpoint trusted owner entry.{bearer_token}: The service account's API key
Step 3. Create an AWS endpoint
Complete these steps once for each private endpoint in your AWS account that will be used to privately connect to one or more of your Serverless clusters. If you connect additional clusters to the same private endpoint, you do not need to make additional changes in your AWS account.
Make a note of the availability zones where your cluster is deployed in this region.
On the Amazon VPC Console in your AWS account, click Your VPCs in the sidebar.
Locate the VPC ID of the VPC you want to create your endpoint in.
Cockroach Labs recommends that you use a VPC that has subnets in the availability zones where your cluster is deployed, and that your application or service is also deployed in the same availability zones. You can choose a different VPC for the private endpoint as long as it is peered to the VPC your application is running in and the private endpoint is configured to be DNS-accessible across the peered VPCs.
On the Your VPCs page, locate the IPv4 CIDR corresponding to the VPC you chose in step 4.
Click Subnets in the sidebar.
Locate the subnet IDs corresponding to the VPC you chose in step 4.
Click Security Groups in the sidebar.
Click Create security group to create a security group within your VPC. The security group allows inbound access from your application or source program on Port 26257:
- In the Security group name field, enter a name for the security group.
- In the Description field, enter a description for the security group.
- From the VPC dropdown, select the VPC you chose in Step 4.
- In the Inbound rules section, click Add rule.
- Enter 26257 in the Port range field.
- In the Source field, enter the CIDR range from Step 5.
- Click Create security group.
Use either the Amazon VPC Console or the AWS Command Line Interface (CLI) to continue:
- Click Endpoints in the sidebar.
- Click Create Endpoint.
- On the Create Endpoint page, for the Service Category field, select Find service by name.
- In the Service Name field, enter the Service Name copied from the connection dialog in Step 1.
- Click Verify.
- In the VPC field, enter the ID of the VPC you want to create your endpoint in.
- Verify that the subnets are pre-populated.
- In the Security group section, select the security group you created in Step 8 and uncheck the box for default security group.
Click Create Endpoint.
The VPC Endpoint ID displays.
Copy the Endpoint ID to your clipboard and return to CockroachDB Cloud's Add PrivateLink dialog.
Substitute the values from the previous steps and run the following AWS CLI command:
aws ec2 create-vpc-endpoint --region {REGION} \ --vpc-id {VPC_ID} \ --subnet-ids {SUBNET_ID1} {SUBNET_ID2} \ --vpc-endpoint-type Interface \ --security-group-ids {SECURITY_GROUP_ID1} {SECURITY_GROUP_ID2} \ --service-name {SERVICE_NAME_PROVIDED_BY_COCKROACH}Locate the VPC Endpoint ID in the CLI output.
Copy the Endpoint ID to your clipboard and return to CockroachDB Cloud's Add PrivateLink dialog.
Step 4. Verify the endpoint ID
- Click Next.
- Enter the Endpoint ID, then click Validate. If validation fails, check the endpoint ID and try again. Otherwise, click Next.
- Follow the instructions in the dialog to enable private DNS name for the endpoint in AWS. When this option is enabled, CockroachDB Cloud maintains private DNS records in the VPC for the cluster.
- Click Complete to save the configuration and close the dialog.
Step 5. Enable private DNS
Allow CockroachDB Cloud to modify the private DNS name for the endpoint in AWS. When this option is enabled, CockroachDB Cloud maintains private DNS records in the VPC for your cluster.
Use either the Amazon VPC Console or the AWS Command Line Interface (CLI) to continue:
- On the Amazon VPC Console Endpoints page, select the endpoint you created.
- Click Actions.
- Click Modify Private DNS Names.
- Check the Enable Private DNS Name checkbox.
- Click Modify Private DNS Name.
- In the CockroachDB Cloud Console, click Complete to save the configuration and close the dialog.
After the endpoint status changes to Available on the Amazon VPC Console Endpoints page, run the following AWS CLI command:
aws ec2 modify-vpc-endpoint --region {REGION} \
--vpc-endpoint-id {VPC_ENDPOINT_ID} \
--private-dns-enabled
The endpoint status will change to Pending.
After a short (less than 5 minute) delay, the status will change from Pending Request to Pending and then to Available. You can now connect to your cluster.
What's next?
Was this helpful?
