BYOC AWS private networking setup

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/guides/infrastructure/01_deployment_options/byoc/03_onboarding/03_network_setup/01_aws.md)

ClickHouse BYOC on AWS supports two private connection options including VPC Peering and AWS PrivateLink.

## Prerequisites[​](#common-prerequisites "Direct link to Prerequisites")

Common steps required by both VPC peering and Privatelink.

### Enable private load balancer for ClickHouse BYOC[​](#step-enable-private-load-balancer-for-clickhouse-byoc "Direct link to Enable private load balancer for ClickHouse BYOC")

Contact ClickHouse Support to enable Private Load Balancer.

## Set up VPC peering[​](#aws-vpc-peering "Direct link to Set up VPC peering")

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

Create a peering connection

### Create a peering connection[​](#step-1-create-a-peering-connection "Direct link to 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

### Accept the peering connection request[​](#step-2-accept-the-peering-connection-request "Direct link to 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

### Add destination to ClickHouse VPC route tables[​](#step-3-add-destination-to-clickhouse-vpc-route-tables "Direct link to 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

### Add destination to the target VPC route tables[​](#step-4-add-destination-to-the-target-vpc-route-tables "Direct link to 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

### Edit security group to allow peered VPC access[​](#step-5-edit-security-group-to-allow-peered-vpc-access "Direct link to 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.

## Set up PrivateLink[​](#setup-privatelink "Direct link to Set up PrivateLink")

AWS PrivateLink provides secure, private connectivity to your ClickHouse BYOC services without requiring VPC peering or internet gateways. Traffic flows entirely within the AWS network, never traversing the public internet.

Request PrivateLink Setup

### Request PrivateLink Setup[​](#step-1-request-privatelink-setup "Direct link to Request PrivateLink Setup")

Contact [ClickHouse Support](https://clickhouse.com/cloud/bring-your-own-cloud) to request PrivateLink setup for your BYOC deployment. No specific information is required at this stage—simply indicate that you want to set up PrivateLink connectivity.

ClickHouse Support will enable the necessary infrastructure components, including **the private load balancer** and **PrivateLink service endpoint**.

Create an Endpoint in Your VPC

### Create an Endpoint in Your VPC[​](#step-2-create-endpoint "Direct link to Create an Endpoint in Your VPC")

After ClickHouse Support has enabled PrivateLink on their side, you need to create a VPC endpoint in your client application VPC to connect to the ClickHouse PrivateLink service.

1. **Obtain the Endpoint Service Name**:
   - ClickHouse Support will provide you with the Endpoint Service name
   - You can also find it in the AWS VPC console under "Endpoint Services" (filter by service name or look for ClickHouse services)

2. **Create the VPC Endpoint**:
   - Navigate to the AWS VPC Console → Endpoints → Create Endpoint
   - Select "Find service by name" and enter the Endpoint Service name provided by ClickHouse Support
   - Choose your VPC and select subnets (one per availability zone is recommended)
   - **Important**: Enable "Private DNS names" for the endpoint—this is required for DNS resolution to work correctly
   - Select or create a security group for the endpoint
   - Click "Create Endpoint"

References

**DNS Requirements**:

- Enable "Private DNS names" when creating the VPC endpoint
- Ensure your VPC has "DNS Hostnames" enabled (VPC Settings → DNS resolution and DNS hostnames)

These settings are required for the PrivateLink DNS to function correctly.

3. **Approve the Endpoint Connection**:
   - After creating the endpoint, you need to approve the connection request
   - In the VPC Console, go to "Endpoint Connections"
   - Find the connection request from ClickHouse and click "Accept" to approve it

Add Endpoint ID to Service Allowlist

### Add Endpoint ID to Service Allowlist[​](#step-3-add-endpoint-id-allowlist "Direct link to Add Endpoint ID to Service Allowlist")

Once your VPC endpoint is created and the connection is approved, you need to add the Endpoint ID to the allowlist for each ClickHouse service you want to access via PrivateLink.

1. **Obtain your Endpoint ID**:

   - In the AWS VPC Console, go to Endpoints
   - Select your newly created endpoint
   - Copy the Endpoint ID (it will look like `vpce-xxxxxxxxxxxxxxxxx`)
2. **Contact ClickHouse Support**:

   - Provide the Endpoint IDs to ClickHouse Support
   - Specify which ClickHouse services should allow access from this endpoint
   - ClickHouse Support will add the Endpoint ID to the service allowlist

Connect to ClickHouse via PrivateLink

### Connect to ClickHouse via PrivateLink[​](#step-4-connect-via-privatelink "Direct link to Connect to ClickHouse via PrivateLink")

After the Endpoint ID is added to the allowlist, you can connect to your ClickHouse service using the PrivateLink endpoint.

The PrivateLink endpoint format is similar to the public endpoint, but includes a `vpce` subdomain. For example:

- **Public endpoint**: `h5ju65kv87.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`
- **PrivateLink endpoint**: `h5ju65kv87.vpce.mhp0y4dmph.us-west-2.aws.clickhouse-byoc.com`

DNS resolution in your VPC will automatically route traffic through the PrivateLink endpoint when you use the `vpce` subdomain format.

### PrivateLink Access Control[​](#privatelink-access-control "Direct link to PrivateLink Access Control")

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