📣
TiDB Cloud Premium is now in public preview. Unlimited growth, instant elasticity, advanced security for enterprise workloads. Try it out →
​
Sign InStart for Free
AI
Developer
Best Practices
API
​
Sign InStart for Free

Connect to a TiDB Cloud Dedicated Cluster via AWS PrivateLink

This document describes how to connect to your TiDB Cloud Dedicated cluster 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:

Private endpoint architecture

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

Restrictions

  • Only users with the Organization Owner or Project Owner role can create private endpoints.
  • The private endpoint and the TiDB cluster you want to connect to 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.

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 cluster

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

  1. Select a TiDB cluster
  2. Create an AWS interface endpoint
  3. Create a private endpoint connection
  4. Enable private DNS
  5. 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

  1. On the My TiDB page, click the name of your target TiDB Cloud Dedicated cluster 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.

Step 2. Create an AWS interface endpoint

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.

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

  2. 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 CLI or using the AWS Management Console.

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

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

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

    1. Sign in to the AWS Management Console and open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

    2. Click Endpoints in the navigation pane, and then click Create Endpoint in the upper-right corner.

      The Create endpoint page is displayed.

      Verify endpoint service

    3. In the Endpoint settings area, fill in a name tag if needed, and then select the Endpoint services that use NLBs and GWLBs option.

    4. In the Service settings area, enter the service name ${your_endpoint_service_name} from the generated command (--service-name ${your_endpoint_service_name}).

    5. Click Verify service.

    6. In the Network settings area, select your VPC in the drop-down list.

    7. In the Subnets area, select the availability zones where your TiDB cluster is located.

    8. In the Security groups area, select your security group properly.

    9. Click Create endpoint.

    Step 3. Create a private endpoint connection

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

    Step 4. Enable private DNS

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

      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.

      To enable private DNS in your AWS Management Console:

      1. Go to VPC > Endpoints.

      2. Right-click your endpoint ID and select Modify private DNS name.

      3. Select the Enable for this endpoint check box.

      4. Click Save changes.

        Enable private DNS

      Step 5. Connect to your TiDB cluster

      After you have accepted the private endpoint connection, 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 Connect With drop-down list, select your preferred connection method. The corresponding connection string is displayed at the bottom of the dialog.
      3. Connect to your cluster with the connection string.

      Private endpoint status reference

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

      • Cluster-level Networking page: navigate to the My TiDB page of your organization, click the name of your target TiDB Cloud Dedicated cluster to go to its overview page, and then click Settings > Networking in the left navigation pane.
      • Project-level Network Access page: navigate to the My TiDB page of your organization, click the Project view tab, locate your target project, click for the project, and then click Network Access under Project Settings.

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

      Use IPv6 connectivity over a private endpoint

      TiDB Cloud Dedicated supports inbound IPv6 connectivity over AWS PrivateLink.

      In TiDB Cloud, you can configure the IP protocol type for each TiDB node group independently. To connect to a TiDB Cloud Dedicated cluster over IPv6, switch the IP protocol type of the target node group to dual-stack, and then create a dual-stack AWS interface endpoint as follows:

      Step 1. Switch the IP protocol type to dual-stack

      After TiDB Cloud Support enables the IPv6 connectivity feature for your organization, you can switch the IP protocol type in the TiDB Cloud console.

      1. Navigate to the My TiDB page of your organization, click the name of your target cluster to go to its overview page, and then click Settings > Networking in the left navigation pane.
      2. Each TiDB Cloud Dedicated cluster has a default TiDB node group. If your cluster has multiple node groups, select your target TiDB node group from the TiDB Node Group list in the upper-right corner.
      3. In the AWS Private Endpoints section, click Edit.
      4. In the AWS Private Endpoints Connection Settings dialog, select Dual Stack (IPv4 + IPv6) as the IP protocol type, and then click Save.

      The IP protocol type can only be changed after the cluster is created.

      Step 2. Create a dual-stack AWS interface endpoint for IPv6

      Create an AWS interface endpoint as described in Step 2. Create an AWS interface endpoint, and note the following:

      • For IP address type, select Dualstack to assign both IPv4 and IPv6 addresses to the endpoint network interfaces.

      • For Subnets, select subnets that each have both an IPv4 CIDR block and an IPv6 CIDR block.

      • If you use the AWS CLI, append --ip-address-type dualstack to the generated 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} --ip-address-type dualstack

      Then complete Step 3 through Step 5 to create the private endpoint connection and connect to your cluster over IPv6.

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

      Manage security groups

      Was this page helpful?