Azure Private Link

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/cloud/guides/security/02_connectivity/private_networking/04_azure-privatelink.md)

Scale plan feature

Azure Private Link is available in the Scale and Enterprise plans. To upgrade, visit the plans page in the cloud console.

This guide shows how to use Azure Private Link to provide private connectivity via a virtual network between Azure (including customer-owned and Microsoft Partner services) and ClickHouse Cloud. Azure Private Link simplifies the network architecture and secures the connection between endpoints in Azure by eliminating data exposure to the public internet.

Azure supports cross-region connectivity via Private Link. This enables you to establish connections between VNets located in different regions where you have ClickHouse services deployed.

Note

Additional charges may be applied to inter-region traffic. Please check the latest Azure documentation.

**Please complete the following steps to enable Azure Private Link:**

1. Obtain Azure connection alias for Private Link
2. Create a Private Endpoint in Azure
3. Add the Private Endpoint Resource ID to your ClickHouse Cloud organization
4. Add the Private Endpoint Resource ID to your services allow list
5. Access your ClickHouse Cloud service using Private Link

Note

ClickHouse Cloud Azure PrivateLink has switched from using resourceGUID to Resource ID filters. You can still use resourceGUID, as it is backward-compatible, but we recommend switching to Resource ID filters. To migrate, simply create a new endpoint using the Resource ID, attach it to the service, and remove the old resourceGUID-based one.

## Attention[​](#attention "Direct link to Attention")

ClickHouse attempts to group your services to reuse the same published [Private Link service](https://learn.microsoft.com/en-us/azure/private-link/private-link-service-overview) within the Azure region. However, this grouping isn't guaranteed, especially if you spread your services across multiple ClickHouse organizations.
If you already have Private Link configured for other services in your ClickHouse organization, you can often skip most of the steps because of that grouping and proceed directly to the final step: [Add the Private Endpoint Resource ID to your services allow list](#add-private-endpoint-id-to-services-allow-list).

Find Terraform examples at the ClickHouse [Terraform Provider repository](https://github.com/ClickHouse/terraform-provider-clickhouse/tree/main/examples/).

## Obtain Azure connection alias for Private Link[​](#obtain-azure-connection-alias-for-private-link "Direct link to Obtain Azure connection alias for Private Link")

### Option 1: ClickHouse Cloud console[​](#option-1-clickhouse-cloud-console "Direct link to Option 1: ClickHouse Cloud console")

In the ClickHouse Cloud console, open the service that you would like to connect via PrivateLink, then open the **Settings** menu. Click on the **Set up private endpoint** button. Make a note of the `Service name` and `DNS name` which will be used for setting up Private Link.

Make a note of the `Service name` and `DNS name`, they will be needed in the next steps.

### Option 2: API[​](#option-2-api "Direct link to Option 2: API")

Before you get started, you'll need a ClickHouse Cloud API key. You can [create a new key](/docs/cloud/manage/openapi) or use an existing one.

Once you have your API key, set the following environment variables before running any commands:

```
REGION=<region code, use Azure format, for example: westus3>
PROVIDER=azure
KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<set ClickHouse organization ID>
SERVICE_NAME=<Your ClickHouse service name>
```

Get your ClickHouse `INSTANCE_ID` by filtering by region, provider and service name:

```
INSTANCE_ID=$(curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" \
"https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services" | \
jq ".result[] | select (.region==\"${REGION:?}\" and .provider==\"${PROVIDER:?}\" and .name==\"${SERVICE_NAME:?}\") | .id " -r)
```

Obtain your Azure connection alias and Private DNS hostname for Private Link:

```
curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | jq  .result
{
  "endpointServiceId": "production-westus3-0-0.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.westus3.azure.privatelinkservice",
  "privateDnsHostname": "xxxxxxxxxx.westus3.privatelink.azure.clickhouse.cloud"
}
```

Make a note of the `endpointServiceId`. You'll use it in the next step.

## Create a private endpoint in Azure[​](#create-private-endpoint-in-azure "Direct link to Create a private endpoint in Azure")

References

This section covers ClickHouse-specific details for configuring ClickHouse via Azure Private Link. Azure-specific steps are provided as a reference to guide you on where to look, but they may change over time without notice from the Azure cloud provider. Please consider Azure configuration based on your specific use case.

Please note that ClickHouse isn't responsible for configuring the required Azure private endpoints and DNS records.

For any issues related to Azure configuration tasks, contact Azure Support directly.

In this section, we're going to create a Private Endpoint in Azure. You can use either the Azure Portal or Terraform.

### Option 1: Using Azure Portal to create a private endpoint in Azure[​](#option-1-using-azure-portal-to-create-a-private-endpoint-in-azure "Direct link to Option 1: Using Azure Portal to create a private endpoint in Azure")

In the Azure Portal, open **Private Link Center → Private Endpoints**.

Open the Private Endpoint creation dialog by clicking on the **Create** button.

---

In the following screen, specify the following options:

- **Subscription** / **Resource Group**: Please choose the Azure subscription and resource group for the Private Endpoint.
- **Name**: Set a name for the **Private Endpoint**.
- **Region**: Choose a region where the deployed VNet that will be connected to ClickHouse Cloud via Private Link.

After you have completed the above steps, click the **Next: Resource** button.

---

Select the option **Connect to an Azure resource by resource ID or alias**.

For the **Resource ID or alias**, use the `endpointServiceId` you have obtained from the [Obtain Azure connection alias for Private Link](#obtain-azure-connection-alias-for-private-link) step.

Click **Next: Virtual Network** button.

---

- **Virtual network**: Choose the VNet you want to connect to ClickHouse Cloud using Private Link
- **Subnet**: Choose the subnet where Private Endpoint will be created

Optional:

- **Application security group**: You can attach ASG to Private Endpoint and use it in Network Security Groups to filter network traffic to/from Private Endpoint.

Click **Next: DNS** button.

Click the **Next: Tags** button.

---

Optionally, you can attach tags to your Private Endpoint.

Click the **Next: Review + create** button.

---

Finally, click the **Create** button.

The **Connection status** of the created Private Endpoint will be in **Pending** state. It will change to **Approved** state once you add this Private Endpoint to the service allow list.

Open the network interface associated with Private Endpoint and copy the **Private IPv4 address**(10.0.0.4 in this example), you will need this information in the next steps.

### Option 2: Using Terraform to create a private endpoint in Azure[​](#option-2-using-terraform-to-create-a-private-endpoint-in-azure "Direct link to Option 2: Using Terraform to create a private endpoint in Azure")

Use the template below to use Terraform to create a Private Endpoint:

```
resource "azurerm_private_endpoint" "example_clickhouse_cloud" {
  name                = var.pe_name
  location            = var.pe_location
  resource_group_name = var.pe_resource_group_name
  subnet_id           = var.pe_subnet_id