AWS PrivateLink

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/guides/security/02_connectivity/private_networking/02_aws-privatelink.md)

Scale plan feature

AWS PrivateLink is available in the Scale and Enterprise plans. To upgrade, visit the plans page in the cloud console.

You can use [AWS PrivateLink](https://aws.amazon.com/privatelink/) to establish secure connectivity between VPCs, AWS services, your on-premises systems, and ClickHouse Cloud without exposing traffic to the public Internet. This document outlines the steps to connect to ClickHouse Cloud using AWS PrivateLink.

To restrict access to your ClickHouse Cloud services exclusively through AWS PrivateLink addresses, follow the instructions provided by ClickHouse Cloud [IP Access Lists](/docs/cloud/security/setting-ip-filters).

Note

ClickHouse Cloud supports [cross-region PrivateLink](https://aws.amazon.com/about-aws/whats-new/2024/11/aws-privatelink-across-region-connectivity/) from the following regions:

- sa-east-1
- il-central-1
- me-south-1
- eu-central-2
- eu-north-1
- eu-south-2
- eu-west-3
- eu-south-1
- eu-west-2
- eu-west-1
- eu-central-1
- ca-west-1
- ca-central-1
- ap-northeast-1
- ap-southeast-2
- ap-southeast-1
- ap-northeast-2
- ap-northeast-3
- ap-south-1
- ap-southeast-4
- ap-southeast-3
- ap-south-2
- ap-east-1
- af-south-1
- us-west-2
- us-west-1
- us-east-2
- us-east-1
  Pricing considerations: AWS will charge users for cross region data transfer, see pricing [here](https://aws.amazon.com/privatelink/pricing/).

**Please complete the following to enable AWS PrivateLink**:

1. Obtain Endpoint "Service name".
2. Create AWS Endpoint.
3. Add "Endpoint ID" to ClickHouse Cloud organization.
4. Add "Endpoint ID" to ClickHouse service allow list.

Find Terraform examples [here](https://github.com/ClickHouse/terraform-provider-clickhouse/tree/main/examples/).

## Important considerations[​](#considerations "Direct link to Important considerations")

ClickHouse attempts to group your services to reuse the same published [service endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-share-your-services.html#endpoint-service-overview) within the AWS region. However, this grouping isn't guaranteed, especially if you spread your services across multiple ClickHouse organizations.
If you already have PrivateLink configured for other services in your ClickHouse organization, you can often skip most of the steps because of that grouping and proceed directly to the final step: Add ClickHouse "Endpoint ID" to ClickHouse service allow list.

## Prerequisites for this process[​](#prerequisites "Direct link to Prerequisites for this process")

Before you get started you will need:

1. Your AWS account.
2. [ClickHouse API key](/docs/cloud/manage/openapi) with the necessary permissions to create and manage private endpoints on ClickHouse side.

## Steps[​](#steps "Direct link to Steps")

Follow these steps to connect your ClickHouse Cloud services via AWS PrivateLink.

### Obtain endpoint "Service name"[​](#obtain-endpoint-service-info "Direct link to Obtain endpoint \"Service name\"")

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

In the ClickHouse Cloud console, open the service you want to connect via PrivateLink, then navigate to the **Settings** menu.

Make a note of the `Service name` and `DNS name`, then [move onto next step](#create-aws-endpoint).

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

First, 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>
```

Get your ClickHouse `INSTANCE_ID` by filtering by region, provider and service name:

```
INSTANCE_ID=$(curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services" | \
jq ".result[] | select (.region==\"${REGION:?}\" and .provider==\"${PROVIDER:?}\" and .name==\"${SERVICE_NAME:?}\") | .id " -r)
```

Obtain `endpointServiceId` and `privateDnsHostname` for your PrivateLink configuration:

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

This command should return something like:

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

Make a note of the `endpointServiceId` and `privateDnsHostname` [move onto next step](#create-aws-endpoint).

### Create AWS endpoint[​](#create-aws-endpoint "Direct link to Create AWS endpoint")

References

This section covers ClickHouse-specific details for configuring ClickHouse via AWS PrivateLink. AWS-specific steps are provided as a reference to guide you on where to look, but they may change over time without notice from the AWS cloud provider. Please consider AWS configuration based on your specific use case.

Please note that ClickHouse isn't responsible for configuring the required AWS VPC endpoints, security group rules or DNS records.

If you previously enabled "private DNS names" while setting up PrivateLink and are experiencing difficulties configuring new services via PrivateLink, please contact ClickHouse support. For any other issues related to AWS configuration tasks, contact AWS Support directly.

#### Option 1: AWS console[​](#option-1-aws-console "Direct link to Option 1: AWS console")

Open the AWS console and Go to **VPC** → **Endpoints** → **Create endpoints**.

Select **Endpoint services that use NLBs and GWLBs** and use `Service name`console or `endpointServiceId`API you got from [Obtain Endpoint "Service name"](#obtain-endpoint-service-info)  step in **Service Name** field. Click **Verify service**:

If you want to establish a cross-regional connection via PrivateLink, enable the "Cross region endpoint" checkbox and specify the service region. The service region is where the ClickHouse instance is running.

If you get a "Service name couldn't be verified." error, please contact Customer Support to request adding new regions to the supported regions list.

Next, select your VPC and subnets:

As an optional step, assign Security groups/Tags:

Note

Make sure that ports `443`, `8443`, `9440`, `3306` are allowed in the security group.

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

#### Option 2: AWS CloudFormation[​](#option-2-aws-cloudformation "Direct link to Option 2: AWS CloudFormation")

Next, you need to create a VPC Endpoint using `Service name`console or `endpointServiceId`API you got from [Obtain Endpoint "Service name"](#obtain-endpoint-service-info)  step.
Make sure to use correct subnet IDs, security groups, and VPC ID.

```
Resources:
  ClickHouseInterfaceEndpoint:
    Type: 'AWS::EC2::VPCEndpoint'
    Properties:
      VpcEndpointType: Interface
      PrivateDnsEnabled: false
      ServiceName: <Service name(endpointServiceId), pls see above>
      VpcId: vpc-vpc_id
      SubnetIds:
        - subnet-subnet_id1
        - subnet-subnet_id2
        - subnet-subnet_id3
      SecurityGroupIds:
        - sg-security_group_id1
        - sg-security_group_id2
        - sg-security_group_id3
```

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