|
| 1 | +--- |
| 2 | +title: Connect to a {{{ .premium }}} Instance via AWS PrivateLink |
| 3 | +summary: Learn how to connect to your {{{ .premium }}} instance via private endpoint with AWS. |
| 4 | +--- |
| 5 | + |
| 6 | +# Connect to a {{{ .premium }}} Instance via AWS PrivateLink |
| 7 | + |
| 8 | +This document describes how to connect to your {{{ .premium }}} instance via [AWS PrivateLink](https://aws.amazon.com/privatelink). |
| 9 | + |
| 10 | +> **Tip:** |
| 11 | +> |
| 12 | +> To learn how to connect to a {{{ .starter }}} or {{{ .essential }}} cluster via AWS PrivateLink, see [Connect to {{{ .starter }}} or Essential via AWS PrivateLink](/tidb-cloud/set-up-private-endpoint-connections-serverless.md). |
| 13 | +
|
| 14 | +TiDB Cloud supports highly secure and one-way access to the TiDB Cloud service hosted in an AWS VPC via [AWS PrivateLink](https://aws.amazon.com/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. |
| 15 | + |
| 16 | +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. |
| 17 | + |
| 18 | +The architecture of the private endpoint is as follows: |
| 19 | + |
| 20 | + |
| 21 | + |
| 22 | +For more detailed definitions of the private endpoint and endpoint service, see the following AWS documents: |
| 23 | + |
| 24 | +- [What is AWS PrivateLink?](https://docs.aws.amazon.com/vpc/latest/privatelink/what-is-privatelink.html) |
| 25 | +- [AWS PrivateLink concepts](https://docs.aws.amazon.com/vpc/latest/privatelink/concepts.html) |
| 26 | + |
| 27 | +## Restrictions |
| 28 | + |
| 29 | +- Only users with the `Organization Owner` role can create private endpoint connections. |
| 30 | +- The private endpoint and the TiDB instance you want to connect to must be located in the same region. |
| 31 | + |
| 32 | +## Prerequisites |
| 33 | + |
| 34 | +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](https://console.aws.amazon.com/). |
| 35 | + |
| 36 | +## Set up a private endpoint connection and connect to your instance |
| 37 | + |
| 38 | +To connect to your {{{ .premium }}} instance via a private endpoint, follow these steps: |
| 39 | + |
| 40 | +1. [Select a TiDB instance](#step-1-select-a-tidb-instance) |
| 41 | +2. [Create an AWS interface endpoint](#step-2-create-an-aws-interface-endpoint) |
| 42 | +3. [Create a private endpoint connection](#step-3-create-a-private-endpoint-connection) |
| 43 | +4. [Enable private DNS](#step-4-enable-private-dns) |
| 44 | +5. [Connect to your TiDB instance](#step-5-connect-to-your-tidb-instance) |
| 45 | + |
| 46 | +If you have multiple instances, you need to repeat these steps for each instance that you want to connect to using AWS PrivateLink. |
| 47 | + |
| 48 | +### Step 1. Select a TiDB instance |
| 49 | + |
| 50 | +1. On the [**TiDB Instances**](https://tidbcloud.com/tidbs) page of your TiDB Cloud web console, click the name of your target TiDB instance to go to its overview page. |
| 51 | +2. Click **Connect** in the upper-right corner. A connection dialog is displayed. |
| 52 | +3. In the **Connection Type** drop-down list, select **Private Endpoint**, and then click **Create Private Endpoint Connection**. |
| 53 | + |
| 54 | +> **Note:** |
| 55 | +> |
| 56 | +> 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 by clicking **Settings** > **Networking** in the left navigation pane. |
| 57 | +
|
| 58 | +### Step 2. Create an AWS interface endpoint |
| 59 | + |
| 60 | +> **Note:** |
| 61 | +> |
| 62 | +> For each {{{ .premium }}} instance, the corresponding endpoint service is automatically created 3 to 4 minutes after the instance creation. |
| 63 | +
|
| 64 | +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. |
| 65 | + |
| 66 | +1. Fill in the **Your VPC ID** and **Your Subnet IDs** fields. You can find these IDs from your [AWS Management Console](https://console.aws.amazon.com/). For multiple subnets, enter the IDs separated by spaces. |
| 67 | +2. Click **Generate Command** to get the following endpoint creation command. |
| 68 | + |
| 69 | + ```bash |
| 70 | + 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} |
| 71 | + ``` |
| 72 | + |
| 73 | +Then, you can create an AWS interface endpoint either using the AWS CLI or using the [AWS Management Console](https://aws.amazon.com/console/). |
| 74 | + |
| 75 | +<SimpleTab> |
| 76 | +<div label="Use AWS CLI"> |
| 77 | + |
| 78 | +To use the AWS CLI to create a VPC interface endpoint, perform the following steps: |
| 79 | + |
| 80 | +1. Copy the generated command and run it in your terminal. |
| 81 | +2. Record the VPC endpoint ID you just created. |
| 82 | + |
| 83 | +> **Tip:** |
| 84 | +> |
| 85 | +> - Before running the command, you need to have AWS CLI installed and configured. See [AWS CLI configuration basics](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html) for details. |
| 86 | +> |
| 87 | +> - 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 instance is located. In this case, you can contact [PingCAP Technical Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support). |
| 88 | + |
| 89 | +</div> |
| 90 | +<div label="Use AWS Console"> |
| 91 | + |
| 92 | +To use the AWS Management Console to create a VPC interface endpoint, perform the following steps: |
| 93 | + |
| 94 | +1. Sign in to the [AWS Management Console](https://aws.amazon.com/console/) and open the Amazon VPC console at [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/). |
| 95 | +2. Click **Endpoints** in the navigation pane, and then click **Create Endpoint** in the upper-right corner. |
| 96 | + |
| 97 | + The **Create endpoint** page is displayed. |
| 98 | + |
| 99 | +  |
| 100 | + |
| 101 | +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. |
| 102 | +4. In the **Service settings** area, enter the service name `${your_endpoint_service_name}` from the generated command (`--service-name ${your_endpoint_service_name}`). |
| 103 | +5. Click **Verify service**. |
| 104 | +6. In the **Network settings** area, select your VPC in the drop-down list. |
| 105 | +7. In the **Subnets** area, select the availability zones where your TiDB instance is located. |
| 106 | + |
| 107 | + > **Tip:** |
| 108 | + > |
| 109 | + > 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 instance is located. In this case, contact [PingCAP Technical Support](https://docs.pingcap.com/tidbcloud/tidb-cloud-support). |
| 110 | + |
| 111 | +8. In the **Security groups** area, select your security group properly. |
| 112 | + |
| 113 | + > **Note:** |
| 114 | + > |
| 115 | + > Make sure the selected security group allows inbound access from your EC2 instances on port `4000` or a customer-defined port. |
| 116 | + |
| 117 | +9. Click **Create endpoint**. |
| 118 | + |
| 119 | +</div> |
| 120 | +</SimpleTab> |
| 121 | + |
| 122 | +### Step 3. Create a private endpoint connection |
| 123 | + |
| 124 | +1. Go back to the TiDB Cloud console. |
| 125 | +2. On the **Create AWS Private Endpoint Connection** page, enter your VPC endpoint ID. |
| 126 | +3. Click **Create Private Endpoint Connection**. |
| 127 | + |
| 128 | +> **Tip:** |
| 129 | +> |
| 130 | +> You can view and manage private endpoint connections on the **Networking** page of your target TiDB instance. To access this page, click **Settings** > **Networking** in the left navigation pane. |
| 131 | + |
| 132 | +### Step 4. Enable private DNS |
| 133 | + |
| 134 | +Enable private DNS in AWS. You can either use the AWS CLI or the AWS Management Console. |
| 135 | + |
| 136 | +<SimpleTab> |
| 137 | +<div label="Use AWS CLI"> |
| 138 | + |
| 139 | +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. |
| 140 | + |
| 141 | +```bash |
| 142 | +aws ec2 modify-vpc-endpoint --vpc-endpoint-id ${your_vpc_endpoint_id} --private-dns-enabled |
| 143 | +``` |
| 144 | + |
| 145 | +Alternatively, you can find the command on the **Networking** page of your instance. Locate the private endpoint and click **...** > **Enable DNS** in the **Action** column. |
| 146 | + |
| 147 | +</div> |
| 148 | +<div label="Use AWS Console"> |
| 149 | + |
| 150 | +To enable private DNS in your AWS Management Console: |
| 151 | + |
| 152 | +1. Go to **VPC** > **Endpoints**. |
| 153 | +2. Right-click your endpoint ID and select **Modify private DNS name**. |
| 154 | +3. Select the **Enable for this endpoint** check box. |
| 155 | +4. Click **Save changes**. |
| 156 | + |
| 157 | +  |
| 158 | + |
| 159 | +</div> |
| 160 | +</SimpleTab> |
| 161 | + |
| 162 | +### Step 5. Connect to your TiDB instance |
| 163 | + |
| 164 | +After you have accepted the private endpoint connection, you are redirected back to the connection dialog. |
| 165 | + |
| 166 | +1. Wait for the private endpoint connection status to change from **System Checking** to **Active** (approximately 5 minutes). |
| 167 | +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. |
| 168 | +3. Connect to your instance with the connection string. |
| 169 | + |
| 170 | +> **Tip:** |
| 171 | +> |
| 172 | +> If you cannot connect to the instance, the reason might be that the security group of your VPC endpoint in AWS is not properly set. See [this FAQ](#troubleshooting) for solutions. |
| 173 | + |
| 174 | +### Private endpoint status reference |
| 175 | + |
| 176 | +When you use private endpoint connections, the statuses of private endpoints and private endpoint services are displayed on the instance-level **Networking** page: |
| 177 | + |
| 178 | +1. Switch to your target instance using the combo box in the upper-left corner. |
| 179 | +2. Click **Settings** > **Networking** in the left navigation pane. |
| 180 | + |
| 181 | +The possible statuses of a private endpoint are explained as follows: |
| 182 | + |
| 183 | +- **Not Configured**: The endpoint service is created but the private endpoint is not created yet. |
| 184 | +- **Pending**: Waiting for processing. |
| 185 | +- **Active**: Your private endpoint is ready to use. You cannot edit a private endpoint in this status. |
| 186 | +- **Deleting**: The private endpoint is being deleted. |
| 187 | +- **Failed**: The private endpoint creation fails. You can click **Edit** in that row to retry the creation. |
| 188 | + |
| 189 | +The possible statuses of a private endpoint service are explained as follows: |
| 190 | + |
| 191 | +- **Creating**: The endpoint service is being created, which takes 3 to 5 minutes. |
| 192 | +- **Active**: The endpoint service is created, regardless of whether the private endpoint is created or not. |
| 193 | +- **Deleting**: The endpoint service or the instance is being deleted, which takes 3 to 5 minutes. |
| 194 | + |
| 195 | +## Troubleshooting |
| 196 | + |
| 197 | +### I cannot connect to a TiDB instance via a private endpoint after enabling private DNS. Why? |
| 198 | + |
| 199 | +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. |
| 200 | + |
| 201 | + |
0 commit comments