Connect to a TiDB Cloud Dedicated Cluster via Private Endpoint with AWS

This document describes how to connect to your TiDB Cloud Dedicated cluster via private endpoint with AWS.

Tip

To learn how to connect to a TiDB Cloud Serverless cluster via private endpoint, see Connect to TiDB Cloud Serverless via Private Endpoint. To learn how to connect to a TiDB Cloud Dedicated cluster via private endpoint with Google Cloud, see Connect to TiDB Cloud Dedicated via Private Service Connect with Google Cloud.

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

Only the Organization Owner and the Project Owner roles can create private endpoints.
The private endpoint and the TiDB cluster to be connected must be located in the same region.

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 connection and connect to your cluster

To connect to your TiDB Cloud Dedicated cluster via a private endpoint, complete the follow these steps:

Select a TiDB cluster
Create an AWS interface endpoint
Fill in your endpoint ID
Enable private DNS and create connection
Connect to your TiDB cluster

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

Step 1. Select a TiDB cluster

On the Clusters page, click the name of your target TiDB cluster to go to its overview page.
Click Connect in the upper-right corner. A connection dialog is displayed.
In the Connection Type drop-down list, select Private Endpoint, and then click Create Private Endpoint Connection.

Note

If you have already created a private endpoint connection, the active endpoint will appear in the connection dialog. To create additional private endpoint connections, navigate to the Networking page in the left navigation pane.

Step 2. Create an AWS interface endpoint

Note

For each TiDB Cloud Dedicated cluster created after March 28, 2023, the corresponding endpoint service is automatically created 3 to 4 minutes after the cluster creation.

If you see the TiDB Private Link Service is ready message, the corresponding endpoint service is ready. You can provide the following information to create the endpoint.

Fill in the Your VPC ID and Your Subnet IDs fields. You can find these IDs from your AWS Management Console. For multiple subnets, enter the IDs separated by spaces.

Click Generate Command to get the following endpoint creation command.

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, you can 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:

Sign in to the AWS Management Console and open the Amazon VPC console at https://console.aws.amazon.com/vpc/.
Click Endpoints in the navigation pane, and then click Create Endpoint in the upper-right corner.
The Create endpoint page is displayed.
Select Other endpoint services.
Enter the service name ${your_endpoint_service_name} from the generated command (--service-name ${your_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:

Copy the generated command and run it in your terminal.
Record the VPC endpoint ID you just created.

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.

Step 3. Fill in your endpoint ID

Go back to the TiDB Cloud console.
On the Create AWS Private Endpoint Connection page, enter your VPC endpoint ID.

Step 4. Enable private DNS and create connection

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 following aws ec2 modify-vpc-endpoint command from the Create Private Endpoint Connection page and run it in your AWS CLI.

aws ec2 modify-vpc-endpoint --vpc-endpoint-id ${your_vpc_endpoint_id} --private-dns-enabled

Alternatively, you can find the command on the Networking page of your cluster. Locate the private endpoint and click ...* > Enable DNS in the Action column.

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

Then you can connect to your TiDB cluster.

Tip

You can view and manage private endpoint connections on two pages:

Cluster-level Networking page: click Networking in the left navigation pane of the cluster overview page.
Project-level Network Access page: click Network Access in the left navigation pane of the Project Settings page.

Step 5. Connect to your TiDB cluster

After you have accepted the private endpoint connection, you are redirected back to the connection dialog.

Wait for the private endpoint connection status to change from System Checking to Active (approximately 5 minutes).
In the Connect With drop-down list, select your preferred connection method. The corresponding connection string is displayed at the bottom of the dialog.
Connect to your cluster with the connection string.

Tip

If you cannot connect to the cluster, the reason might be that the security group of your VPC endpoint in AWS is not properly set. See this FAQ for solutions.

Private endpoint status reference

When you use private endpoint connections, the statuses of private endpoints or private endpoint services are displayed on the following pages:

Cluster-level Networking page: click Networking in the left navigation pane of the cluster overview page.
Project-level Network Access page: click Network Access in the left navigation pane of the Project Settings page.

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

Not Configured: The endpoint service is created but the private endpoint is not created yet.
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.