Set Up Private Endpoint Connections

TiDB Cloud supports highly secure and one-way access to the TiDB Cloud service hosted in an AWS VPC via the AWS PrivateLink, as if the service were in your own VPC. A private endpoint is exposed in your VPC and you can create a connection to the TiDB Cloud service via the endpoint with permission.

Powered by AWS PrivateLink, the endpoint connection is secure and private, and does not expose your data to the public internet. In addition, the endpoint connection supports CIDR overlap and is easier for network management.

The architecture of the private endpoint is as follows:

Private endpoint architecture

For more detailed definitions of the private endpoint and endpoint service, see the following AWS documents:

Restrictions

Currently, TiDB Cloud supports private endpoint connection only when the endpoint service is hosted in AWS. If the service is hosted in Google Cloud Platform (GCP), the private endpoint is not applicable.
The private endpoint support is provided only for the TiDB Cloud Dedicated Tier, not for the Developer Tier.
Private endpoint connection across regions is not supported.

In most scenarios, you are recommended to use private endpoint connection over VPC peering. However, in the following scenarios, you should use VPC peering instead of private endpoint connection:

You are using a TiCDC cluster to replicate data from a source TiDB cluster to a target TiDB cluster across regions, to get high availability. Currently, private endpoint does not support cross-region connection.
You are using a TiCDC cluster to replicate data to a downstream cluster (such as Amazon Aurora, MySQL, and Kafka) but you cannot maintain the endpoint service on your own.
You are connecting to PD or TiKV nodes directly.

Set up a private endpoint with AWS

This section describes how to set up a private endpoint with AWS PrivateLink.

In addition to the prerequisites, there are 5 steps to set up a private endpoint connection with AWS PrivateLink:

Choose a TiDB cluster
Check the service endpoint region
Create an AWS interface endpoint
Accept the endpoint connection
Enable private DNS

If you have multiple clusters, you need to repeat these steps for each cluster that you want to connect to using AWS PrivateLink.

Prerequisites

TiDB Cloud supports private endpoints only for Dedicated Tier clusters. You are expected to create a Dedicated Tier cluster before creating a private endpoint. For detailed instructions, see Create a TiDB Cluster in TiDB Cloud.

To start setting up a private endpoint, open the private endpoint creation page:

Click the Project Settings tab in the TiDB Cloud console.
Click Private Endpoint on the left menu.
Click Add on the Private Endpoint page.

Step 1. Choose a TiDB cluster

Click the drop-down list and choose an available TiDB cluster.
Click Next.

Step 2. Check the service endpoint region

Your service endpoint region is selected by default. Have a quick check and click Next.

Note

The default region is where your cluster is located. Do not change it. Cross-region private endpoint is currently not supported.

Step 3. Create an AWS interface endpoint

TiDB Cloud begins creating an endpoint service, which takes 3 to 4 minutes.

When the endpoint service is created, take a note of your endpoint service name from the command in the lower area of the console.

aws ec2 create-vpc-endpoint --vpc-id <your_vpc_id> --region <your_region> --service-name <your_endpoint_service_name> --vpc-endpoint-type Interface --subnet-ids <your_application_subnet_ids>

Then create an AWS interface endpoint either using the AWS Management Console or using the AWS CLI.

Use AWS Console
Use AWS CLI

To use the AWS Management Console to create a VPC interface endpoint, perform the following steps:

Go to VPC > Endpoints.
Click Create Endpoint.
The Create endpoint page is displayed.
Select Other endpoint services.
Enter the endpoint service name.
Click Verify service.
Select your VPC in the drop-down list.
Select the availability zones where your TiDB cluster is located in the Subnets area.
Tip
If your service is spanning across more than three availability zones (AZs), you might not be able to select AZs in the Subnets area. This issue occurs when there is an extra AZ in your selected region in addition to the AZs where your TiDB cluster is located. In this case, contact PingCAP Technical Support.
Select your security group properly in the Security groups area.
Note
Make sure the selected security group allows inbound access from your EC2 instances on Port 4000 or a customer-defined port.
Click Create endpoint.

To use the AWS CLI to create a VPC interface endpoint, perform the following steps:

Fill in the VPC ID and Subnet IDs fields on the private endpoint creation page. You can get the IDs from your AWS Management Console.
Copy the command in the lower area of the page and run it in your terminal. Then click Next.

Tip

Before running the command, you need to have AWS CLI installed and configured. See AWS CLI configuration basics for details.
If your service is spanning across more than three availability zones (AZs), you will get an error message indicating that the VPC endpoint service does not support the AZ of the subnet. This issue occurs when there is an extra AZ in your selected region in addition to the AZs where your TiDB cluster is located. In this case, you can contact PingCAP Technical Support.
You cannot copy the command until TiDB Cloud finishes creating an endpoint service in the background.

Step 4. Accept the endpoint connection

Go back to the TiDB Cloud console.
Fill in the box with your VPC endpoint ID on the Create Private Endpoint page.
Click Next.

Step 5. Enable private DNS

Enable private DNS in AWS. You can either use the AWS Management Console or the AWS CLI.

Use AWS Console
Use AWS CLI

To enable private DNS in your AWS Management Console:

Go to VPC > Endpoints.
Right-click your endpoint ID and select Modify private DNS name.
Select the Enable for this endpoint check box.
Click Save changes.

To enable private DNS using your AWS CLI, copy the command and run it in your AWS CLI.

aws ec2 modify-vpc-endpoint --vpc-endpoint-id <your_vpc_endpoint_id> --private-dns-enabled

Click Create in the TiDB Cloud console to finalize the creation of the private endpoint.

Then you can connect to the endpoint service. See Connect to TiDB cluster via private endpoint for details.

Private endpoint status reference

When you use private endpoint connections, the statuses of private endpoints or private endpoint services are displayed on the Private Endpoint page.

The possible statuses of a private endpoint are explained as follows:

Not Configured: You have just created an endpoint service but have not yet created a private endpoint.
Pending: Waiting for processing.
Active: Your private endpoint is ready to use. You cannot edit the private endpoint of this status.
Deleting: The private endpoint is being deleted.
Failed: The private endpoint creation fails. You can click Edit of that row to retry the creation.

The possible statuses of a private endpoint service are explained as follows:

Creating: The endpoint service is being created, which takes 3 to 5 minutes.
Active: The endpoint service is created, no matter whether the private endpoint is created or not.
Deleting: The endpoint service or the cluster is being deleted, which takes 3 to 5 minutes.

Troubleshooting

I cannot connect to a TiDB cluster via a private endpoint after enabling private DNS. Why?

You might need to properly set the security group for your VPC endpoint in the AWS Management Console. Go to VPC > Endpoints. Right-click your VPC endpoint and select the proper Manage security groups. A proper security group within your VPC that allows inbound access from your EC2 instances on Port 4000 or a customer-defined port.

Manage security groups

I cannot enable private DNS. An error is reported indicating that the `enableDnsSupport` and `enableDnsHostnames` VPC attributes are not enabled

Make sure that DNS hostname and DNS resolution are both enabled in your VPC setting. They are disabled by default when you create a VPC in the AWS Management Console.