Skip to main content
ClickHouse BYOC on AWS supports two private connection options including VPC Peering and AWS PrivateLink.

​
Prerequisites

Common steps required by both VPC peering and PrivateLink.

​
Enable private load balancer for ClickHouse BYOC

In the ClickHouse Cloud console, enable the Private load balancer for your BYOC infrastructure.

​
Set up VPC peering

To create or delete VPC peering for ClickHouse BYOC, follow the steps:
1

Create a peering connection

  1. Navigate to the VPC Dashboard in ClickHouse BYOC account.
  2. Select Peering Connections.
  3. Click Create Peering Connection
  4. Set the VPC Requester to the ClickHouse VPC ID.
  5. Set the VPC Accepter to the target VPC ID. (Select another account if applicable)
  6. Click Create Peering Connection.
2

Accept the peering connection request

Go to the peering account, in the (VPC -> Peering connections -> Actions -> Accept request) page customer can approve this VPC peering request.
3

Add destination to ClickHouse VPC route tables

In ClickHouse BYOC account,
  1. Select Route Tables in the VPC Dashboard.
  2. Search for the ClickHouse VPC ID. Edit each route table attached to the private subnets.
  3. Click the Edit button under the Routes tab.
  4. Click Add another route.
  5. Enter the CIDR range of the target VPC for the Destination.
  6. Select “Peering Connection” and the ID of the peering connection for the Target.
4

Add destination to the target VPC route tables

In the peering AWS account,
  1. Select Route Tables in the VPC Dashboard.
  2. Search for the target VPC ID.
  3. Click the Edit button under the Routes tab.
  4. Click Add another route.
  5. Enter the CIDR range of the ClickHouse VPC for the Destination.
  6. Select “Peering Connection” and the ID of the peering connection for the Target.
5

Edit security group to allow peered VPC access

In the ClickHouse BYOC account, you need to update the Security Group settings to allow traffic from your peered VPC. Please contact ClickHouse Support to request the addition of inbound rules that include the CIDR ranges of your peered VPC.
The ClickHouse service should now be accessible from the peered VPC.
To access ClickHouse privately, a private load balancer and endpoint are provisioned for secure connectivity from the user’s peered VPC. The private endpoint follows the public endpoint format with a -private suffix. For example:
  • Public endpoint: h5ju65kv87.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com
  • Private endpoint: h5ju65kv87-private.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com
Optional, after verifying that peering is working, you can request the removal of the public load balancer for ClickHouse BYOC. AWS PrivateLink provides a secure and private connection to your ClickHouse BYOC services without the need for VPC peering or internet gateways. All traffic flows within the AWS network, ensuring that it never traverses the public internet.
Cross-region connections. The Enable private link toggle in the ClickHouse console provisions the endpoint service and covers same-region consumers only. AWS disables cross-region access on endpoint services by default, and the ClickHouse console doesn’t manage it — if your clients are in a different region, you enable it yourself: the endpoint service lives in your BYOC account, so add the consumer regions to its Supported regions list in your own AWS console (see step 3 below). ClickHouse won’t change or reset these values. AWS cross-region data transfer rates apply.
2

Obtain endpoint Service name

  1. In the ClickHouse Cloud console, navigate to the service’s Settings page that you would like to connect to via PrivateLink.
  2. Click “Set up private endpoint”.
  3. In the opened flyout, copy the Service name value — you’ll use it in the next step. (It may take a while for the value to be generated after enabling PrivateLink.)
3

Create endpoint in your network

  1. Open your own AWS console (i.e. the AWS account where your client application is) → VPC → Endpoints → Create endpoints.
  2. Select “Endpoint services that use NLBs and GWLBs” and use Service name obtained from the last step.
  3. Click “Verify service”.
  4. (Optional) 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 your BYOC infrastructure is created. Meanwhile,
    1. Open your BYOC AWS console (i.e. the AWS account where your BYOC infrastructure is created) → VPC → Endpoint services → clickhouse-cloud-infra-xxx → Supported regions.
    2. Add the region where your client application is running to the supported regions list. By default, only the region of this BYOC infrastructure is supported. You can add multiple regions if you want to connect from different regions, and ClickHouse won’t change or reset these values.
  5. Select your VPC and subnets (one per availability zone is recommended).
  6. Important: Enable “Private DNS names” for the endpoint — this is required for Private DNS to function correctly. Private DNS for BYOC endpoints (using the *.vpce.{subdomain} format) leverages AWS PrivateLink’s built-in “Private DNS names” feature. No Route53 records are required — DNS resolution happens automatically when:
    • “Private DNS names” is enabled and
    • “DNS Hostnames” is enabled via VPC Settings → DNS resolution and DNS hostnames. This ensures that connections using the vpce subdomain automatically route through the PrivateLink endpoint without additional DNS configuration.
  7. (Optional) Assign Security groups/Tags.
    Make sure that ports 443, 8443, and 9440 are allowed in the security group.
  8. Click “Create endpoint”, wait a moment for the endpoint to be created.
  9. After creating the endpoint, copy the Endpoint ID value — you’ll use it in the next step.
4

Approve the endpoint connection

  1. Open your BYOC VPC console again → Endpoint services → clickhouse-cloud-infra-xxx → Endpoint connections.
  2. Find the connection request created from your own VPC and click “Accept endpoint connection request” to approve it.
5

Add Endpoint ID to ClickHouse service allow list

  1. In the ClickHouse Cloud console, navigate to the service’s Settings page that you would like to connect to via PrivateLink.
  2. Click “Set up private endpoint”.
  3. In the opened flyout, enter the Endpoint ID obtained from the last step with an optional description.
  4. Click “Create endpoint”.
If you want to allow access from an existing PrivateLink connection, use the existing endpoint dropdown menu. The dropdown will show the existing PrivateLink connections to the services within the same infrastructure.
Last modified on August 3, 2026