Skip to main content

Setting up AWS PrivateLink

You can use AWS PrivateLink to provide connectivity between VPCs, AWS services, your on-premises systems, and ClickHouse Cloud without having your traffic go across the internet. This document describes how to connect to ClickHouse Cloud using AWS PrivateLink, and how to disable access to your ClickHouse Cloud services from addresses other than AWS PrivateLink addresses using ClickHouse Cloud IP Access Lists.

VPC network diagram

This table lists the AWS Regions where ClickHouse Cloud services can be deployed, the associated VPC service name, and Availability Zone IDs. You will need this information to setup AWS PrivateLink to connect to ClickHouse Cloud services.

RegionVPC Service NameAZ IDs
ap-south-1com.amazonaws.vpce.ap-south-1.vpce-svc-0a786406c7ddc3a1baps1-az1 aps1-az2 aps1-az3
ap-southeast-1com.amazonaws.vpce.ap-southeast-1.vpce-svc-0a8b096ec9d2acb01apse1-az1 apse1-az2 apse1-az3
eu-central-1com.amazonaws.vpce.eu-central-1.vpce-svc-0536fc4b80a82b8edeuc1-az2 euc1-az3 euc1-az1
eu-west-1com.amazonaws.vpce.eu-west-1.vpce-svc-066b03c9b5f61c6fceuw1-az2 euw1-az3 euw1-az1
us-east-1com.amazonaws.vpce.us-east-1.vpce-svc-0a0218fa75c646d81use1-az6 use1-az1 use1-az2
us-east-2com.amazonaws.vpce.us-east-2.vpce-svc-0b99748bf269a86b4use2-az1 use2-az2 use2-az3
us-west-2com.amazonaws.vpce.us-west-2.vpce-svc-049bbd33f61271781usw2-az2 usw2-az1 usw2-az3

Create service endpoint

Create a service endpoint, please use a region from the table above.

note

AWS PrivateLink is a regional service (as of today). You can only establish a connection within the same region.

In the AWS console go to VPC > Endpoints > Create endpoints. Click on Other endpoint services and use one of the VPC Service Names from supported regions. Then click on Verify service.

Endpoint settings

important

Please note, AWS PrivateLink connectivity works in tandem with the ClickHouse IP Access List feature.

We strongly recommend enabling IP Access Lists on each ClickHouse Cloud service, otherwise, the PrivateLink traffic filter will not be applied and the ClickHouse Cloud service could potentially be accessible to other ClickHouse PrivateLink customers.

Select VPC and subnets

Select VPC and subnets

Optional: assign Security groups/Tags

note

Make sure that the ClickHouse ports 8443 and 9440 are allowed in the Security group.

After creating the VPC Endpoint, please write down the VPC Endpoint ID, you will need to provide this to ClickHouse Support.

VPC endpoint ID

AWS CloudFormation

Please use correct subnet IDs, security groups and VPC ID.

Resources:
ClickHouseInterfaceEndpoint:
Type: 'AWS::EC2::VPCEndpoint'
Properties:
VpcEndpointType: Interface
PrivateDnsEnabled: false
ServiceName: com.amazonaws.vpce.us-west-2.vpce-svc-049bbd33f61271781
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

Terraform

https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc_endpoint

resource "aws_vpc_endpoint" "this" {
vpc_id = var.vpc_id
service_name = “com.amazonaws.vpce.us-west-2.vpce-svc-049bbd33f61271781"
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
}

Reach out to ClickHouse Support

Click on Help in the ClickHouse Cloud console and choose Support to open a case. Please provide the VPC Endpoint ID(s) and ClickHouse service hostname(s) to ClickHouse Support.

  • VPC Endpoint IDs There may be more than one VPC Endpoint ID, you should have a list of one or more of these from the step where you created the endpoint. This is the section of the UI where the endpoint IDs are located:

    VPC endpoint ID

  • ClickHouse instance URLs: The ClickHouse instance URLs can be found in the Cloud console. Click on a service that you need the URL for and open Connect. The cluster hostname will be available:

    Cluster URL

Once the request is processed, the VPC Endpoint service status will change from pendingAcceptance to Available.

Test connectivity

note

This step validates TCP connectivity between your VPC and ClickHouse cloud infrastructure over PrivateLink.

Please get DNS Names from VPC Endpoint configuration:

Get DNS names

note

Please use this FQDN only for connectivity testing

telnet vpce-08c316c04b3a5623f-bi21tevr.vpce-svc-049bbd33f61271781.us-west-2.vpce.amazonaws.com 9440
Trying 172.31.27.78...
Connected to vpce-08c316c04b3a5623f-bi21tevr.vpce-svc-049bbd33f61271781.us-west-2.vpce.amazonaws.com
Escape character is '^]'.
^]
telnet> Connection closed.
telnet vpce-08c316c04b3a5623f-bi21tevr.vpce-svc-049bbd33f61271781.us-west-2.vpce.amazonaws.com 8443
Trying 172.31.27.78...
Connected to vpce-08c316c04b3a5623f-bi21tevr.vpce-svc-049bbd33f61271781.us-west-2.vpce.amazonaws.com.
Escape character is '^]'.
^]
telnet> Connection closed.

The error below indicates a problem with connectivity.

telnet vpce-08c316c04b3a5623f-bi21tevr.vpce-svc-049bbd33f61271781.us-west-2.vpce.amazonaws.com 9440
Trying 172.31.25.195...
telnet: connect to address 172.31.25.195: No route to host
Trying 172.31.3.200...

Shift network traffic to VPC Endpoint

note

This step switches network traffic from traveliing over the Internet to using the VPC Endpoint.

Before this step:

[[email protected] ~]$ nslookup HOSTNAME.clickhouse.cloud
Server: 172.31.0.2
Address: 172.31.0.2#53

Non-authoritative answer:
Name: HOSTNAME.clickhouse.cloud
Address: 44.226.232.172
Name: HOSTNAME.clickhouse.cloud
Address: 35.82.252.60
Name: HOSTNAME.clickhouse.cloud
Address: 35.85.205.122
After completion of this step:
[[email protected] ~]$ nslookup HOSTNAME.clickhouse.cloud
Server: 172.31.0.2
Address: 172.31.0.2#53

Non-authoritative answer:
Name: HOSTNAME.clickhouse.cloud
Address: 172.31.27.78
Name: HOSTNAME.clickhouse.cloud
Address: 172.31.33.234
Name: HOSTNAME.clickhouse.cloud
Address: 172.31.8.117

AWS Console

Go to VPC Endpoints and right click the VPC Endpoint, then click to Modify private DNS name:

Endpoints menu

On the opened page, please enable the checkbox Enable private DNS names

Modify DNS names

AWS CloudFormation

  • Please update CloudFormation template and set PrivateDnsEnabled to true:
  PrivateDnsEnabled: true
  • Apply the change

Terraform

  • Change the aws_vpc_endpoint resource in Terraform code and set private_dns_enabled to true:
  private_dns_enabled = true
  • Apply the change

Verification

note

IP address ranges may vary.

important

Please make sure ClickHouse instance FQDN is pointed to the internal IP address of your VPC, otherwise connectivity will be established using the Internet. Please find these IP addresses on “Subnets” tab of VPC Endpoint configuration.

Subnets tab

Verify that instance FQDN is pointed to VPC Endpoint ID IP addresses.

nslookup HOSTNAME.clickhouse.cloud
Server:         172.31.0.2
Address: 172.31.0.2#53

Non-authoritative answer:
Name: HOSTNAME.clickhouse.cloud
Address: 172.31.25.195
Name: HOSTNAME.clickhouse.cloud
Address: 172.31.40.109
Name: HOSTNAME.clickhouse.cloud
Address: 172.31.3.200

Verify connectivity to ClickHouse Cloud service

curl https://HOSTNAME.clickhouse.cloud:8443
Ok.
clickhouse-client --host HOSTNAME.clickhouse.cloud \
--secure --port 9440 \
--password PASSWORD
1