Connect to TiDB Cloud Premium via AWS PrivateLink

This document describes how to connect to your TiDB Cloud Premium instance via AWS PrivateLink.

TiDB Cloud supports highly secure and one-way access to the TiDB Cloud service hosted in an AWS VPC via 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:

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

• What is AWS PrivateLink?
• AWS PrivateLink concepts

Restrictions

• Only users with the Organization Owner, Project Owner, or Instance Owner role of the target instance can create private endpoint connections.
• The private endpoint and the TiDB Cloud Premium instance you want to connect to must be located in the same region.

Prerequisites

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

Set up a private endpoint connection and connect to your instance

To connect to your TiDB Cloud Premium instance via a private endpoint, follow these steps:

1. Open the private endpoint connection dialog
2. Create a VPC endpoint in AWS
3. Enter the VPC endpoint ID in TiDB Cloud
4. Enable private DNS
5. Connect to your TiDB Cloud Premium instance

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

Step 1. Open the private endpoint connection dialog

1. On the My TiDB page of your TiDB Cloud console, click the name of your target TiDB Cloud Premium instance to go to its overview page.
2. Click Connect in the upper-right corner. A connection dialog is displayed.
3. In the Connection Type drop-down list, select Private Endpoint, and then click Create Private Endpoint Connection.
4. In the Create AWS Private Endpoint Connection dialog, wait until the TiDB Private Link Service is ready message is displayed.
5. Copy the Endpoint Service Name.

Step 2. Create a VPC endpoint in AWS

After the endpoint service is ready, create a VPC interface endpoint in your AWS account. You can either use the AWS CLI command generated by TiDB Cloud or create the endpoint manually in the AWS Management Console.

To generate an AWS CLI command in TiDB Cloud, expand How to Generate VPC Endpoint ID in the Create AWS Private Endpoint Connection dialog, and then do the following:

1. Enter Your VPC ID.
2. Enter Your Subnet IDs. For multiple subnets, separate the subnet IDs with spaces.
3. Make sure that the subnets are in the availability zones supported by the dialog. Do not use subnets from other availability zones.
4. Click Generate Command.

The generated command is similar to the following:

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}

Step 3. Enter the VPC endpoint ID in TiDB Cloud

1. Go back to the TiDB Cloud console.
2. In the Create AWS Private Endpoint Connection dialog, enter the VPC endpoint ID that you created in AWS into the Your VPC Endpoint ID field.
3. Click Create Private Endpoint.

Step 4. Enable private DNS

After you create the private endpoint in TiDB Cloud, enable private DNS in AWS to complete the private endpoint connection. TiDB Cloud provides the aws ec2 modify-vpc-endpoint command in the Create AWS Private Endpoint Connection dialog. You can also get the command later from the Networking page.

Step 5. Connect to your TiDB Cloud Premium instance

After the private endpoint connection is created, you are redirected back to the connection dialog.

1. Wait for the private endpoint connection status to change from System Checking to Active (approximately 5 minutes).

2. In the Connection Type drop-down list, select Private Endpoint.

3. In the Endpoint ID drop-down list, select the active VPC endpoint that you want to use.

   Only active endpoints are displayed in the Endpoint ID drop-down list. To add more endpoints, go to the Networking page.

4. In the Connect With drop-down list, select your preferred connection method.

5. If the instance does not have a root password, click Set Root Password and set a password first.

6. Copy the connection parameters or connection string from the dialog, and then connect to your instance.

Private endpoint status reference

When you use private endpoint connections, the statuses of private endpoints and private endpoint services are displayed on the instance-level Networking page:

1. Navigate to the My TiDB page of your organization, and then click the name of your target TiDB Cloud Premium instance to go to its overview page.
2. Click Settings > Networking in the left navigation pane.

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 a private endpoint in this status.
• Deleting: The private endpoint is being deleted.
• Failed: The private endpoint creation fails. You can click Edit in 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, regardless of whether the private endpoint is created or not.
• Deleting: The endpoint service or the instance is being deleted, which takes 3 to 5 minutes.

Troubleshooting

I cannot connect to a TiDB Cloud Premium instance 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. To do so, go to VPC > Endpoints, right-click your VPC endpoint, and select Manage security groups. Ensure that the selected security group allows inbound access from your EC2 instances on port 4000 or a customer-defined port.