> ## 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 Azure private networking setup
> Set up VNet peering or Private Link for BYOC on Azure
export const Image = ({img, alt, size = "lg", background}) => {
const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
return ;
};
ClickHouse BYOC on Azure supports two private connection options: [Azure Virtual Network peering](https://learn.microsoft.com/azure/virtual-network/virtual-network-peering-overview) and [Azure Private Link](https://learn.microsoft.com/azure/private-link/private-link-overview). 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--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](https://learn.microsoft.com/azure/virtual-network/virtual-network-peering-overview) and its [requirements and constraints](https://learn.microsoft.com/azure/virtual-network/virtual-network-manage-peering#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](#vnet-peering-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](https://learn.microsoft.com/azure/virtual-network/virtual-network-manage-peering#permissions).
1. Sign in to the [Azure portal](https://portal.azure.com) and switch to the **BYOC subscription**.
2. Search for **Virtual networks** and select the BYOC VNet, which lives in the `clickhouse-cloud--default` resource group.
3. Under **Settings**, select **Peerings**, then select **+ Add**.
4. Fill in both halves of the peering:
5. Click **Add**.
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**.
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**.
The BYOC subnets are protected by a ClickHouse-managed [network security group](https://learn.microsoft.com/azure/virtual-network/network-security-groups-overview) that denies VNet-internal traffic by default. Because the [`VirtualNetwork` service tag](https://learn.microsoft.com/azure/virtual-network/service-tags-overview#available-service-tags) 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.
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](https://learn.microsoft.com/azure/virtual-network/virtual-network-peering-overview#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](https://azure.microsoft.com/pricing/details/virtual-network). 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](https://learn.microsoft.com/azure/virtual-network/update-virtual-network-peering-address-space) 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](https://azure.microsoft.com/pricing/details/virtual-network).
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](https://learn.microsoft.com/azure/virtual-network/virtual-network-manage-peering#delete-a-peering).
Set up Private Link
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.
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 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.)
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.
Add the private endpoint Resource ID to ClickHouse service allow list} id="step-4-add-endpoint-id-to-services-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/`). 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**.
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](https://learn.microsoft.com/en-us/azure/dns/private-dns-getstarted-portal) 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](https://learn.microsoft.com/en-us/azure/dns/private-dns-getstarted-portal#link-the-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:
```bash theme={null}
nslookup h5ju65kv87.privatelink.mhp0y4dmph.westus3.azure.clickhouse-byoc.com
```
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 Private Link is controlled by the service-level **Istio Authorization Policy**, managed by ClickHouse within your BYOC infrastructure.