AWS PrivateLink

After creating the VPC Endpoint, make a note of the `Endpoint ID` value; you'll need it for an upcoming step.

#### Option 3: Terraform[​](#option-3-terraform "Direct link to Option 3: Terraform")

`service_name` below is `Service name`console or `endpointServiceId`API you got from [Obtain Endpoint "Service name"](#obtain-endpoint-service-info)  step

```
resource "aws_vpc_endpoint" "this" {
  vpc_id            = var.vpc_id
  service_name      = "<pls see comment above>"
  vpc_endpoint_type = "Interface"
  security_group_ids = [
    Var.security_group_id1,var.security_group_id2, var.security_group_id3,
  ]
  subnet_ids          = [var.subnet_id1,var.subnet_id2,var.subnet_id3]
  private_dns_enabled = false
  service_region      = "(Optional) If specified, the VPC endpoint will connect to the service in the provided region. Define it for multi-regional PrivateLink connections."
}
```

After creating the VPC Endpoint, make a note of the `Endpoint ID` value; you'll need it for an upcoming step.

#### Set private DNS name for endpoint[​](#set-private-dns-name-for-endpoint "Direct link to Set private DNS name for endpoint")

Note

There are various ways to configure DNS. Please set up DNS according to your specific use case.

You need to point "DNS name", taken from [Obtain Endpoint "Service name"](#obtain-endpoint-service-info)  step, to AWS Endpoint network interfaces. This ensures that services/components within your VPC/Network can resolve it properly.

### Add "Endpoint ID" to ClickHouse service allow list[​](#add-endpoint-id-to-services-allow-list "Direct link to Add \"Endpoint ID\" to ClickHouse service allow list")

#### Option 1: ClickHouse Cloud console[​](#option-1-clickhouse-cloud-console-2 "Direct link to Option 1: ClickHouse Cloud console")

To add, please navigate to the ClickHouse Cloud console, open the service that you would like to connect via PrivateLink then navigate to **Settings**. Click **Set up private endpoint** to open private endpoints settings. Enter the `Endpoint ID` obtained from the [Create AWS Endpoint](#create-aws-endpoint) step. Click "Create endpoint".

Note

If you want to allow access from an existing PrivateLink connection, use the existing endpoint drop-down menu.

To remove please navigate to the ClickHouse Cloud console, find the service, then navigate to **Settings** of the service, find endpoint you would like to remove.Remove it from the list of endpoints.

#### Option 2: API[​](#option-2-api-2 "Direct link to Option 2: API")

You need to add an Endpoint ID to the allow-list for each instance that should be available using PrivateLink.

Set the `ENDPOINT_ID` environment variable using data from [Create AWS Endpoint](#create-aws-endpoint) step.

Set the following environment variables before running any commands:

```
REGION=<Your region code using the AWS format, for example: us-west-2>
PROVIDER=aws
KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
SERVICE_NAME=<Your ClickHouse service name>
```

To add an endpoint ID to an allow-list:

```
cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "add": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
-X PATCH -H "Content-Type: application/json" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" \
-d @pl_config.json | jq
```

To remove an endpoint ID from an allow-list:

```
cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "remove": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
-X PATCH -H "Content-Type: application/json" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" \
-d @pl_config.json | jq
```

### Accessing an instance using PrivateLink[​](#accessing-an-instance-using-privatelink "Direct link to Accessing an instance using PrivateLink")

Each service with Private Link enabled has a public and private endpoint. In order to connect using Private Link, you need to use a private endpoint which will be `privateDnsHostname`API or `DNS Name`console taken from [Obtain Endpoint "Service name"](#obtain-endpoint-service-info).

#### Getting private DNS hostname[​](#getting-private-dns-hostname "Direct link to Getting private DNS hostname")

##### Option 1: ClickHouse Cloud console[​](#option-1-clickhouse-cloud-console-3 "Direct link to Option 1: ClickHouse Cloud console")

In the ClickHouse Cloud console, navigate to **Settings**. Click on the **Set up private endpoint** button. In the opened flyout, copy the **DNS Name**.

##### Option 2: API[​](#option-2-api-3 "Direct link to Option 2: API")

Set the following environment variables before running any commands:

```
KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
INSTANCE_ID=<Your ClickHouse service name>
```

You can retrieve `INSTANCE_ID` from [step](#option-2-api).

```
curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | \
jq .result
```

This should output something like:

```
{
  "endpointServiceId": "com.amazonaws.vpce.us-west-2.vpce-svc-xxxxxxxxxxxxxxxxx",
  "privateDnsHostname": "xxxxxxxxxx.us-west-2.vpce.aws.clickhouse.cloud"
}
```

In this example connection via value of `privateDnsHostname` host name will be routed to PrivateLink, but connection via `endpointServiceId` hostname will be routed over the Internet.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Multiple PrivateLinks in one region[​](#multiple-privatelinks-in-one-region "Direct link to Multiple PrivateLinks in one region")

In most cases, you only need to create a single endpoint service for each VPC. This endpoint can route requests from the VPC to multiple ClickHouse Cloud services.
Please refer [here](#considerations)

### Connection to private endpoint timed out[​](#connection-to-private-endpoint-timed-out "Direct link to Connection to private endpoint timed out")

- Please attach security group to VPC Endpoint.
- Please verify `inbound` rules on security group attached to Endpoint and allow ClickHouse ports.
- Please verify `outbound` rules on security group attached to VM which is used to connectivity test and allow connections to ClickHouse ports.

### Private Hostname: Not found address of host[​](#private-hostname-not-found-address-of-host "Direct link to Private Hostname: Not found address of host")

- Please check your DNS configuration

### Connection reset by peer[​](#connection-reset-by-peer "Direct link to Connection reset by peer")

- Most likely Endpoint ID wasn't added to service allow list, please visit [step](#add-endpoint-id-to-services-allow-list)

### Checking endpoint filters[​](#checking-endpoint-filters "Direct link to Checking endpoint filters")

Set the following environment variables before running any commands:

```
KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<please set ClickHouse organization ID>
INSTANCE_ID=<Instance ID>
```

You can retrieve `INSTANCE_ID` from [step](#option-2-api).

```
curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
-X GET -H "Content-Type: application/json" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" | \
jq .result.privateEndpointIds
```

### Connecting to a remote database[​](#connecting-to-a-remote-database "Direct link to Connecting to a remote database")

Let's say you're trying to use [MySQL](/docs/sql-reference/table-functions/mysql) or [PostgreSQL](/docs/sql-reference/table-functions/postgresql) table functions in ClickHouse Cloud and connect to your database hosted in an Amazon Web Services (AWS) VPC. AWS PrivateLink can't be used to enable this connection securely. PrivateLink is a one-way, unidirectional connection. It allows your internal network or Amazon VPC to connect securely to ClickHouse Cloud, but it doesn't allow ClickHouse Cloud to connect to your internal network.