Skip to main content
Skip to main content
Edit this page

BYOC AWS private networking setup

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​

Set up VPC peering​

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

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.

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.

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.

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.

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.byoc.clickhouse.cloud
  • Private endpoint: h5ju65kv87-private.mhp0y4dmph.us-west-2.aws.byoc.clickhouse.cloud

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.

Note

Make sure the private load balancer is turned on as a prerequisite.

Obtain endpoint "Service name"​

  1. Open your BYOC AWS console (i.e. the AWS account where BYOC infrastructure is created) → VPC → Endpoint services.
  2. Find the service starting with clickhouse-cloud-infra and navigate to its details page.

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 the ClickHouse instance is running.

  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.

    Note

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

  8. Click "Create endpoint", wait a moment for the endpoint to be created.

  9. After creating the endpoint, take a note of the Endpoint ID value. You'll need it for the upcoming step.

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.

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".
Note

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.

  1. In the ClickHouse Cloud console, navigate to service's Settings page.

  2. Click "Set up private endpoint".

  3. In the opened flyout, copy the DNS name.

    Access to ClickHouse services via PrivateLink is controlled at two levels:

    1. Istio Authorization Policy: ClickHouse Cloud's service-level authorization policies
    2. VPC Endpoint Security Group: The security group attached to your VPC endpoint controls which resources in your VPC can use the endpoint
    Note

    The private load balancer's "Enforce inbound rules on PrivateLink traffic" feature is disabled, so access is controlled by Istio authorization policies and your VPC endpoint's security group only.