Skip to main content
ClickHouse BYOC on Azure supports two private connection options: Azure Virtual Network peering and Azure Private Link. Both keep traffic on the Azure backbone so that it never traverses the public internet.

​
Prerequisites

Common steps required by both VNet peering and Private Link.

​
Enable private load balancer for ClickHouse BYOC

In the ClickHouse Cloud console, enable the Private load balancer for your BYOC infrastructure. Both connection options route through this internal load balancer, so neither works until it is enabled. Note down the infrastructure Spoken name. ClickHouse deploys your BYOC infrastructure into your own Azure subscription, into a managed resource group named clickhouse-cloud-<spoken-name>-default. That resource group is where you find the BYOC VNet in the steps below.

​
Set up VNet peering

Please familiarize yourself with Azure Virtual Network peering and its requirements and constraints before you begin. ClickHouse BYOC uses a private load balancer to allow network connectivity through the peering to ClickHouse services.
The example steps are for a simple scenario: one of your VNets peering directly with the BYOC VNet. For advanced scenarios such as hub-and-spoke topologies or on-premises connectivity, some adjustments are required — see Limitations.

​
Additional prerequisites for peering

Non-overlapping address spaces. Peered virtual networks can’t have overlapping IP address ranges. Compare your VNet’s address space with the BYOC VNet’s address space, shown on the BYOC VNet’s Overview page in the Azure portal. If they overlap, use Private Link instead. Permissions. Creating a peering requires the Microsoft.Network/virtualNetworks/virtualNetworkPeerings/write and Microsoft.Network/virtualNetworks/peer/action permissions on both virtual networks. The built-in Network Contributor role includes them. See virtual network peering permissions.
1

Create the peering from the BYOC virtual network

  1. Sign in to the Azure portal and switch to the BYOC subscription.
  2. Search for Virtual networks and select the BYOC VNet, which lives in the clickhouse-cloud-<spoken-name>-default resource group.
  3. Under Settings, select Peerings, then select + Add.
  1. Fill in both halves of the peering:
  1. Click Add.
2

Create the reverse peering, if it wasn't created for you

Azure peering consists of two halves, one per direction, and traffic doesn’t flow until both exist. If the portal created both halves in the previous step, skip this step.If you only created the BYOC-side half — because your VNet is in another subscription or tenant — its state is Initiated. Create the matching half from your own VNet:
  1. Switch to the subscription that owns your VNet, sign in as an account with Network Contributor on it.
  2. Select your VNet, then Peerings → + Add.
  3. Select I know my resource ID, paste the BYOC VNet resource ID, and choose the Directory that owns the BYOC subscription. Select Authenticate if prompted.
  4. Select Add.
3

Verify that both halves are connected

Open Peerings on either virtual network. The Peering status must show Connected on both sides. A half that stays Initiated means its counterpart is missing; a half that shows Disconnected means its counterpart was deleted.No route table changes are needed. Azure automatically installs system routes for the peered address space on both sides. You can confirm this on any network interface in your VNet under Effective routes, where the BYOC address space appears with a next hop type of VNet peering.
4

Allow peered VNet access through the network security group

The BYOC subnets are protected by a ClickHouse-managed network security group that denies VNet-internal traffic by default. Because the VirtualNetwork service tag covers the address space of peered VNets, traffic arriving over the peering is dropped until an inbound allow rule is added.Please contact ClickHouse Support to request the addition of inbound rules that include the CIDR ranges of your peered VNet. Without this step, the peering shows Connected but connections time out.
5

Access ClickHouse service via the peering

To access ClickHouse privately, a private load balancer and endpoint are provisioned for secure connectivity from your peered VNet. The private endpoint follows the public endpoint format with a -private suffix. For example:
  • Public endpoint: h5ju65kv87.mhp0y4dmph.westus3.azure.clickhouse-byoc.com
  • Private endpoint: h5ju65kv87-private.mhp0y4dmph.westus3.azure.clickhouse-byoc.com

​
Limitations

Peering is not transitive. Only the VNet directly peered with the BYOC VNet can reach your services. Clients in a spoke VNet behind a hub, or on-premises clients arriving over ExpressRoute or a VPN gateway, are not covered by a single peering. These topologies need additional configuration such as Allow forwarded traffic and gateway transit — see gateways and on-premises connectivity — or use Private Link instead. Cross-region peering works, but costs more. A peering between VNets in different regions is a global peering. It reaches ClickHouse normally — the BYOC private load balancer is a Standard SKU internal load balancer, and Azure’s restriction on reaching load balancer frontends over a global peering covers only Basic SKU load balancers. What you do pay is added round-trip latency and cross-region data transfer charges. Prefer a same-region peering for latency-sensitive workloads. If a cross-region peering shows Connected but connections still fail, the region is not the cause — the most common reason is that the inbound network security group rule for your address space is missing, so contact ClickHouse Support. Address space changes need a resync. If you resize your VNet’s address space after the peering exists, sync the peering so the new ranges are advertised, and contact ClickHouse Support to extend the inbound network security group rule to cover them. Peering traffic is billed. Azure charges for ingress and egress across a peering. See Virtual network pricing.

​
Delete the peering

Delete the peering from either side. Deleting one half disconnects the link and leaves the other half in a Disconnected state, so delete both halves to clean up fully. See delete a peering. Azure Private Link provides a secure and private connection to your ClickHouse BYOC services. All traffic flows within the Azure network, ensuring that it never traverses the public internet.
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 Private Link.
  2. Click “Set up private endpoint”.
  3. In the opened flyout, copy the Service name (the Private Link service alias) and DNS name values — you’ll use them in the next steps. (It may take a while for the values to be generated after enabling Private Link.)
3

Create a private endpoint in your network

  1. Open your own Azure Portal (i.e. the Azure subscription where your client application is) → Network Foundation → Private endpoints → Create.
  2. On the Basics tab, choose the subscription, resource group, name, and region for the private endpoint. The region should be the region of the VNet your client application connects from.
  3. On the Resource tab, select Connect to an Azure resource by resource ID or alias and enter the Service name obtained from the last step.
  4. On the Virtual Network tab, choose the virtual network and subnet where the private endpoint will be created. Optionally, attach an application security group to filter traffic to the private endpoint.
  5. Continue through the remaining tabs and click Create. The Connection status of the created private endpoint will be in a Pending state until you add its Resource ID to the ClickHouse service allow list in the next steps.
  6. Open the network interface associated with the private endpoint and copy the Private IPv4 address — you’ll use it in the DNS setup step.
4

Add the private endpoint Resource ID to ClickHouse service allow list

To obtain the private endpoint Resource ID, open the private endpoint created earlier in the Azure Portal and click JSON View, then copy the top-level id field (the Resource ID shown at the top of the view, in the form /subscriptions/.../providers/Microsoft.Network/privateEndpoints/<name>). Don’t use the nested id fields inside the properties object:
  1. In the ClickHouse Cloud console, navigate to the service’s Settings page that you would like to connect to via Private Link.
  2. Click “Set up private endpoint”.
  3. In the opened flyout, enter the Resource ID obtained above into the Endpoint ID field with an optional description.
  4. Click “Create endpoint”.
If you want to allow access from an existing Private Link connection, use the existing endpoint dropdown menu. The dropdown will show the existing Private Link connections to the services within the same infrastructure.
No manual approval in the Azure Portal is required — once the Resource ID is added to the allow list, the endpoint connection is automatically approved, and its LinkID is automatically added to the Istio AuthorizationPolicy for the ClickHouse service. The Connection status of the private endpoint in your subscription changes to Approved.
5

Set private DNS name for endpoint

There are various ways to configure DNS. Please set up DNS according to your specific use case.
You need to point all subdomains (wildcard) of the “DNS name” (everything after the service ID, e.g. privatelink.mhp0y4dmph.westus3.azure.clickhouse-byoc.com) to the private endpoint IP address. This ensures that services/components within your VNet can resolve it properly. A typical setup using Azure Private DNS:
  1. Create a Private DNS zone named after the “DNS name” without the leading service ID, for example privatelink.mhp0y4dmph.westus3.azure.clickhouse-byoc.com.
  2. In the zone, create a wildcard record set: for Name type *, and for IP Address enter the private endpoint IP address copied earlier.
  3. Link the Private DNS zone to your virtual network so clients in the VNet can resolve the zone.
Verify the DNS setup from a host inside your VNet — the “DNS name” should resolve to the private endpoint IP:
Last modified on August 12, 2026