Network Authorization

To prevent denial-of-service and brute force password attacks, CockroachCloud requires you to authorize networks that can access your cluster by allowlisting the public IP addresses for your application. Optionally, you can set up Virtual Private Cloud (VPC) peering or AWS PrivateLink for your cluster for enhanced network security and lower network latency.

IP allowlisting

Authorize your application server’s network and your local machine’s network by adding their public IP addresses (in the CIDR format) to the CockroachCloud cluster's allowlist. If you change your location, you will need to authorize the new location’s network, else the connection from that network will be rejected.

• In a development environment, you need to authorize your application server’s network and your local machine’s network. If you change your location, you need to authorize the new location’s network, or else the connection from that network will be rejected.
• In a production environment, you need to authorize your application server’s network.

If your application servers’ IP addresses are not static or you want to limit your cluster's exposure to the public network, you can connect to your CockroachCloud clusters using VPC Peering or AWS PrivateLink instead.

VPC peering

If you select GCP as your cloud provider while creating your CockroachCloud cluster, you can use Google Cloud's VPC Network Peering feature to connect your GCP application directly to your CockroachCloud cluster using internal IP addresses, thus limiting exposure to the public network and reducing network latency.

Setting up a VPC peering connection between your CockroachCloud cluster and GCP application is a two-part process:

1. Configure the IP range and size while creating the CockroachCloud cluster
2. Configure a peering connection after creating the cluster

Configure the IP range and size while creating your CockroachCloud cluster

While creating your CockroachCloud cluster, enable VPC peering and configure the IP address range and size (in CIDR format) for the CockroachCloud network based on the following considerations:

• To adhere to GCP's overlapping subnets restriction, configure an IP range that doesn't overlap with the IP ranges in your application network.
• The IP range and size cannot be changed after the cluster is created. Configuring a smaller IP range size may limit your ability to expand into multiple regions in the future. We recommend configuring an IP range size of /16 or lower.

Alternatively, you can use CockroachCloud's default IP range and size (172.28.0.0/14) as long as it doesn't overlap with the IP ranges in your network.

Establish a VPC Peering connection after creating your CockroachCloud cluster

After creating your CockroachCloud cluster, request a peering connection from CockroachCloud's Networking page. Then accept the request by running the gcloud command displayed your screen. You can check the status of the connection on the Peering tab on the Networking page. The status is shown as PENDING until you accept the connection request from the GCP side. After the connection is successfully established, the status changes to ACTIVE. You can then select a connection method and connect to your cluster.

AWS PrivateLink

If your cloud provider is AWS, you can use AWS PrivateLink to securely connect your AWS application with your CockroachCloud cluster using a private endpoint. Like VPC Peering, a PrivateLink connection will prevent your traffic from being exposed to the public internet and reduce network latency.

There are four steps to setting up an AWS PrivateLink connection between your CockroachCloud cluster and AWS application:

1. Set up a cluster
2. Create an AWS endpoint
3. Verify the endpoint ID
4. Enable private DNS

Set up a cluster

1. Use the CockroachCloud Console to create your CockroachCloud 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.

2. Navigate to the Networking page.

3. Select the PrivateLink tab.

4. Click Set up a PrivateLink connection to open the connection modal.

Create an AWS endpoint

1. If you have a multi-region cluster, select the region to create a connection in. Skip this step if you have a single-region cluster.
2. Copy the Service Name shown in the connection modal.
3. On the Amazon VPC Console, click Your VPCs in the sidebar.

4. Locate the VPC ID of the VPC you want to create your endpoint in.

   This will probably be the same VPC as the VPC your EC2 instances and application are running in. You can also choose a different VPC as long as it is peered to the VPC your application is running in.

5. On the Your VPCs page, locate the IPv4 CIDR corresponding to the VPC you chose in Step 3.

6. Click Subnets in the sidebar.

7. Locate the subnet IDs corresponding to the VPC you chose in Step 3.

8. Click Security Groups in the sidebar.

9. Click Create security group to create a security group within your VPC that allows inbound access from your EC2 instances 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 3.
   • 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 4.
   • Click Create security group.

Use either the Amazon VPC Console or the AWS Command Line Interface (CLI) to continue:

1. Click Endpoints in the sidebar.
2. Click Create Endpoint.
3. On the Create Endpoint page, for the Service Category field, select Find service by name.
4. In the Service Name field, enter the Service Name copied from the connection modal in Step 1.
5. Click Verify.
6. In the VPC field, enter the ID of the VPC you want to create your endpoint in.
7. Verify that the subnets are pre-populated.
8. In the Security group section, select the security group you created in Step 8 and uncheck the box for default security group.

9. Click Create Endpoint.

   The VPC Endpoint ID displays.

10. Copy the Endpoint ID to your clipboard and return to CockroachCloud's Add PrivateLink modal.

1. 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
   

2. Locate the VPC Endpoint ID in the CLI output.

3. Copy the Endpoint ID to your clipboard and return to CockroachCloud's Add PrivateLink modal.

Verify the endpoint ID

1. Paste the Endpoint ID you created into the VPC Endpoint ID field.
2. Click Verify.
3. CockroachCloud will accept the endpoint request. You can confirm the request acceptance by checking if the status is listed as Available on the Amazon VPC Console Endpoints page.

Enable private DNS

1. On the Amazon VPC Console Endpoints page, select the endpoint you created.
2. Click Actions.
3. Click Modify Private DNS Names.
4. Check the Enable Private DNS Name checkbox.
5. Click Modify Private DNS Name.

Alternatively, use the AWS CLI to modify the Private DNS Name:

1. After the endpoint status changes to Available, run the following AWS CLI command:

   $ aws ec2 modify-vpc-endpoint --region $REGION \
   --private-dns-enabled --vpc-endpoint-id $VPC_ENDPOINT_ID
   

The endpoint status will change to Pending.

After a short (less than 5 minute) delay, the status will change to Available. You can now connect to your cluster.

See also

• Client Connection Parameters
• Connect to Your CockroachCloud Cluster