> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-vortex-format.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# BYOC AWS private networking setup
> Set up VPC Peering or PrivateLink for BYOC on AWS
export const Image = ({img, alt, size = "lg"}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
return ;
};
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. 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.
Go to the peering account, in the (VPC -> Peering connections -> Actions -> Accept request) page customer can approve this VPC peering request.
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.
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.
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.
Set up PrivateLink
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.
Make sure the **private load balancer** is turned on as a prerequisite.
Obtain endpoint Service name} id="step-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.)
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.
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} id="step-5-add-endpoint-id-to-services-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.
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
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.