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

If you require two or more AWS Private Links within the same AWS region, then please note: In ClickHouse, we have a VPC Endpoint service at a regional level. When you setup two or more VPC Endpoints in the same VPC - from the AWS VPC perspective - you are utilizing just a single AWS Private Link. In such a situation where you need two or more AWS Private Links configured within the same region, please just create just one VPC Endpoint in your VPC, and request that ClickHouse configure the same VPC Endpoint ID for all of your ClickHouse services in the same AWS region.

note

AWS PrivateLink can be enabled only on ClickHouse Cloud Production services

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

info

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

If only traffic from your PrivateLink should be allowed, set the IP Access list to DenyAll by setting the Access List to Specific Locations and then removing all entries from the list. Your Access List will then report No traffic is currently able to access this service, but your PrivateLink addresses will be allowed. If you do need to allow traffic from select public IP addresses (for example Grafana Cloud) then add those IP addresses to your IP Access list.

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:

[ec2-user@ip-172-31-29-231 ~]$ 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:
[ec2-user@ip-172-31-29-231 ~]$ 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.

info

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

Connecting to RDS​

AWS PrivateLink does not currently work for connecting to private RDS instances using the PostgreSQL table engine and the MySQL table engine.

To use the above table engines, your RDS instances must be publicly accessible and must whitelist ClickHouse Cloud’s external IP addresses. Please see our Static IPs page for more information on our external IP addresses, and this AWS guide on how to make your RDS instances publicly available.

note

Connecting to private RDS instances may be possible in the future using VPC Peering, which may be supported for Dedicated services. Development and Production services cannot support VPC Peering because of ClickHouse Cloud’s multi-tenant architecture and lack of separate VPC per tenant. If you are interested in VPC Peering, please contact support@clickhouse.com.