Azure Private Link - ClickHouse Documentation

В этом руководстве показано, как использовать Azure Private Link для организации частного подключения через виртуальную сеть между Azure (включая сервисы, принадлежащие клиентам и партнёрам Microsoft) и ClickHouse Cloud. Azure Private Link упрощает сетевую архитектуру и защищает соединение между конечными точками в Azure, исключая передачу данных через публичный интернет. Azure поддерживает межрегиональное подключение через Private Link. Это позволяет устанавливать соединения между VNet, расположенными в разных регионах, где у вас развернуты сервисы ClickHouse.

За межрегиональный трафик может взиматься дополнительная плата. Ознакомьтесь с актуальной документацией Azure.

Чтобы включить Azure Private Link, выполните следующие шаги:

Получите alias подключения Azure для Private Link
Создайте частную конечную точку в Azure
Добавьте Resource ID частной конечной точки в организацию ClickHouse Cloud
Добавьте Resource ID частной конечной точки в список разрешённых для ваших сервисов
Подключитесь к сервису ClickHouse Cloud через Private Link

В ClickHouse Cloud Azure PrivateLink вместо фильтров resourceGUID теперь используются фильтры Resource ID. resourceGUID по-прежнему можно использовать, так как он обратно совместим, однако мы рекомендуем перейти на фильтры Resource ID. Для миграции просто создайте новую конечную точку с использованием Resource ID, подключите её к сервису и удалите старую конечную точку на основе resourceGUID.

Внимание

ClickHouse старается группировать ваши сервисы, чтобы повторно использовать один и тот же опубликованный сервис Private Link в рамках региона Azure. Однако такая группировка не гарантируется, особенно если ваши сервисы распределены между несколькими организациями ClickHouse. Если Private Link уже настроен для других сервисов в вашей организации ClickHouse, благодаря этой группировке вы часто можете пропустить большинство шагов и сразу перейти к последнему: добавить Resource ID частной конечной точки в список разрешённых для ваших сервисов. Примеры Terraform можно найти в ClickHouse репозитории Terraform-провайдера.

Получите псевдоним подключения Azure для Private Link

Вариант 1: консоль ClickHouse Cloud

В консоли ClickHouse Cloud откройте сервис, к которому вы хотите подключиться через PrivateLink, затем откройте меню Настройки. Нажмите кнопку Настроить частную конечную точку. Запишите Service name и DNS name — они понадобятся для настройки Private Link. Запишите Service name и DNS name — они понадобятся на следующих шагах.

Вариант 2: API

Перед началом работы вам понадобится API-ключ ClickHouse Cloud. Вы можете создать новый ключ или использовать существующий. Получив API-ключ, задайте следующие переменные окружения перед выполнением любых команд:

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>

Получите ClickHouse INSTANCE_ID, выполнив фильтрацию по региону, провайдеру и имени сервиса:

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)

Получите псевдоним подключения Azure и имя хоста Private DNS для 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"
}

Запишите endpointServiceId. Он понадобится на следующем этапе.

Создайте частную конечную точку в Azure

В этом разделе рассматриваются особенности настройки ClickHouse через Azure Private Link, относящиеся именно к ClickHouse. Шаги со стороны Azure приведены только в справочных целях, чтобы сориентировать вас, где искать нужные настройки, однако со временем они могут измениться без предварительного уведомления со стороны облачного провайдера Azure. Учитывайте особенности конфигурации Azure в соответствии с вашим конкретным сценарием использования.Обратите внимание, что ClickHouse не отвечает за настройку необходимых частных конечных точек Azure и DNS-записей.Если у вас возникнут проблемы, связанные с задачами настройки Azure, обращайтесь напрямую в Azure Support.

В этом разделе мы создадим частную конечную точку в Azure. Для этого можно использовать либо Azure Portal, либо Terraform.

Вариант 1: Использование Azure Portal для создания частной конечной точки в Azure

В Azure Portal откройте Private Link Center → Private Endpoints. Откройте диалог создания частной конечной точки, нажав кнопку Create.

На следующем экране укажите следующие параметры:

Subscription / Resource Group: выберите подписку Azure и группу ресурсов для частной конечной точки.
Name: задайте имя для частной конечной точки.
Region: выберите регион, в котором развёрнута VNet, которая будет подключаться к ClickHouse Cloud через Private Link.

После этого нажмите кнопку Next: Resource.

Выберите вариант Connect to an Azure resource by resource ID or alias. В поле Resource ID or alias используйте endpointServiceId, полученный на шаге Obtain Azure connection alias for Private Link. Нажмите кнопку Next: Virtual Network.

Virtual network: выберите VNet, которую хотите подключить к ClickHouse Cloud через Private Link
Subnet: выберите подсеть, в которой будет создана частная конечная точка

Необязательно:

Application security group: можно привязать ASG к частной конечной точке и использовать её в Network Security Groups для фильтрации сетевого трафика к/от частной конечной точки.

Нажмите кнопку Next: DNS. Нажмите кнопку Next: Tags.

При необходимости вы можете добавить теги к своей частной конечной точке. Нажмите кнопку Next: Review + create.

Наконец, нажмите кнопку Create. У созданной частной конечной точки Connection status будет иметь состояние Pending. Оно изменится на Approved, как только вы добавите эту частную конечную точку в список разрешённых для сервиса. Откройте сетевой интерфейс, связанный с частной конечной точкой, и скопируйте Private IPv4 address (в этом примере — 10.0.0.4) — эта информация понадобится вам на следующих шагах.

Вариант 2: Создание частной конечной точки в Azure с помощью Terraform

Используйте приведённый ниже шаблон Terraform для создания частной конечной точки:

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

  private_service_connection {
    name                              = "test-pl"
    private_connection_resource_alias = "<data from 'Obtain Azure connection alias for Private Link' step>"
    is_manual_connection              = true
  }
}

Получение Resource ID частной конечной точки

Чтобы использовать Private Link, необходимо добавить Resource ID подключения частной конечной точки в список разрешённых для вашего сервиса. Resource ID частной конечной точки доступен в Azure Portal. Откройте частную конечную точку, созданную на предыдущем шаге, и нажмите JSON View: В разделе properties найдите поле id и скопируйте его значение: Предпочтительный способ: использование Resource ID Устаревший способ: использование resourceGUID resourceGUID по-прежнему можно использовать для обратной совместимости. Найдите поле resourceGuid и скопируйте его значение:

Настройка DNS для Private Link

Вам потребуется создать зону Private DNS (${location_code}.privatelink.azure.clickhouse.cloud) и привязать её к вашей VNet, чтобы получить доступ к ресурсам через Private Link.

Создание зоны Private DNS

Вариант 1: Через Azure Portal Следуйте этому руководству, чтобы создать частную зону DNS в Azure через Azure Portal. Вариант 2: С помощью Terraform Используйте следующий шаблон Terraform, чтобы создать зону Private DNS:

resource "azurerm_private_dns_zone" "clickhouse_cloud_private_link_zone" {
  name                = "${var.location}.privatelink.azure.clickhouse.cloud"
  resource_group_name = var.resource_group_name
}

Создайте подстановочную DNS-запись

Создайте подстановочную запись и направьте её на свою частную конечную точку: Вариант 1: через Azure Portal

Откройте группу ресурсов MyAzureResourceGroup и выберите частную зону ${region_code}.privatelink.azure.clickhouse.cloud.
Выберите + Record set.
В поле Name введите *.
В поле IP Address введите IP-адрес, указанный для Private Endpoint.
Выберите OK.

Вариант 2: с помощью Terraform Используйте следующий шаблон Terraform, чтобы создать подстановочную DNS-запись:

resource "azurerm_private_dns_a_record" "example" {
  name                = "*"
  zone_name           = var.zone_name
  resource_group_name = var.resource_group_name
  ttl                 = 300
  records             = ["10.0.0.4"]
}

Создайте связь с виртуальной сетью

Чтобы связать зону Private DNS с виртуальной сетью, необходимо создать связь с виртуальной сетью. Вариант 1: Через Azure Portal Следуйте этому руководству, чтобы связать виртуальную сеть с вашей зоной Private DNS. Вариант 2: Через Terraform

DNS можно настроить разными способами. Настройте его в соответствии с вашим сценарием использования.

Нужно, чтобы «DNS name», полученное на шаге Получение псевдонима подключения Azure для Private Link, указывало на IP-адрес частной конечной точки. Это гарантирует, что сервисы/компоненты в вашей VPC/сети смогут корректно его разрешать.

Проверьте настройку DNS

Домен xxxxxxxxxx.westus3.privatelink.azure.clickhouse.cloud должен разрешаться в IP-адрес частной конечной точки (в этом примере — 10.0.0.4).

nslookup xxxxxxxxxx.westus3.privatelink.azure.clickhouse.cloud.
Server: 127.0.0.53
Address: 127.0.0.53#53

Non-authoritative answer:
Name: xxxxxxxxxx.westus3.privatelink.azure.clickhouse.cloud
Address: 10.0.0.4

Добавьте Resource ID частной конечной точки в организацию ClickHouse Cloud

Вариант 1: консоль ClickHouse Cloud

Чтобы добавить конечную точку в организацию, перейдите к шагу Добавьте Resource ID частной конечной точки в список разрешённых сервисов. Если добавить Resource ID частной конечной точки в список разрешённых сервисов через консоль ClickHouse Cloud, он автоматически будет добавлен и в организацию. Чтобы удалить конечную точку, откройте Сведения об организации -> Частные конечные точки и нажмите кнопку удаления.

Вариант 2: API

Перед запуском любых команд задайте следующие переменные окружения:

PROVIDER=azure
KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<set ClickHouse organization ID>
ENDPOINT_ID=<Private Endpoint Resource ID>
REGION=<region code, use Azure format>

Задайте переменную окружения ENDPOINT_ID, используя данные из шага Obtaining the Private Endpoint Resource ID. Выполните следующую команду, чтобы добавить частную конечную точку:

cat <<EOF | tee pl_config_org.json
{
  "privateEndpoints": {
    "add": [
      {
        "cloudProvider": "azure",
        "id": "${ENDPOINT_ID:?}",
        "description": "Azure private endpoint",
        "region": "${REGION:?}"
      }
    ]
  }
}
EOF

Вы также можете выполнить следующую команду, чтобы удалить частную конечную точку:

cat <<EOF | tee pl_config_org.json
{
  "privateEndpoints": {
    "remove": [
      {
        "cloudProvider": "azure",
        "id": "${ENDPOINT_ID:?}",
        "region": "${REGION:?}"
      }
    ]
  }
}
EOF

После добавления или удаления частной конечной точки выполните следующую команду, чтобы применить изменения к вашей организации:

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" -X PATCH -H "Content-Type: application/json" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}" -d @pl_config_org.json

Добавьте Resource ID частной конечной точки в список разрешённых для ваших сервисов

По умолчанию сервис ClickHouse Cloud недоступен через Private Link, даже если подключение по Private Link одобрено и установлено. Вам нужно явно добавить Resource ID частной конечной точки для каждого сервиса, который должен быть доступен через Private Link.

Вариант 1: консоль ClickHouse Cloud

В консоли ClickHouse Cloud откройте сервис, к которому нужно подключиться через PrivateLink, затем перейдите в раздел Настройки. Введите Resource ID, полученный на предыдущем шаге.

Если вы хотите разрешить доступ через существующее подключение PrivateLink, выберите существующую конечную точку в раскрывающемся меню.

Вариант 2: API

Перед выполнением команд задайте эти переменные окружения:

PROVIDER=azure
KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<set ClickHouse organization ID>
ENDPOINT_ID=<Private Endpoint Resource ID>
INSTANCE_ID=<Instance ID>

Выполните это для каждого сервиса, который должен быть доступен через Private Link. Выполните следующую команду, чтобы добавить частную конечную точку в список разрешённых для сервиса:

cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "add": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

Вы также можете выполнить следующую команду, чтобы удалить частную конечную точку из списка разрешённых для сервиса:

cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "remove": [
      "${ENDPOINT_ID:?}"
    ]
  }
}
EOF

После добавления частной конечной точки в список разрешённых сервиса или её удаления из него выполните следующую команду, чтобы применить изменения к вашей организации:

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" -X PATCH -H "Content-Type: application/json" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" -d @pl_config.json | jq

Доступ к вашему сервису ClickHouse Cloud через Private Link

У каждого сервиса с включенным Private Link есть публичная и частная конечная точка. Чтобы подключиться через Private Link, нужно использовать частную конечную точку — privateDnsHostname^API или DNS name^console, указанные в разделе Получение псевдонима подключения Azure для Private Link.

Получение имени хоста Private DNS

Вариант 1: консоль ClickHouse Cloud

В консоли ClickHouse Cloud перейдите в раздел Настройки. Нажмите кнопку Set up private endpoint. В открывшейся выдвижной панели скопируйте DNS Name.

Вариант 2: API

Задайте следующие переменные окружения перед запуском любых команд:

KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<set ClickHouse organization ID>
INSTANCE_ID=<Instance ID>

Выполните следующую команду:

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}/privateEndpointConfig" | jq  .result

Вы должны получить ответ примерно следующего вида:

{
  ...
  "privateDnsHostname": "xxxxxxx.<region code>.privatelink.azure.clickhouse.cloud"
}

В этом примере соединение с именем хоста xxxxxxx.region_code.privatelink.azure.clickhouse.cloud будет направляться через Private Link. В то же время xxxxxxx.region_code.azure.clickhouse.cloud будет направляться через интернет. Используйте privateDnsHostname, чтобы подключаться к вашему сервису ClickHouse Cloud через Private Link.

Устранение неполадок

Проверка настроек DNS

Выполните следующую команду:

nslookup <dns name>

где “имя DNS” — это privateDnsHostname^API или DNS name^console из Получение псевдонима подключения Azure для Private Link В ответ вы должны получить следующее:

Non-authoritative answer:
Name: <dns name>
Address: 10.0.0.4

Соединение сброшено удалённой стороной

Скорее всего, Resource ID частной конечной точки не был добавлен в список разрешённых для сервиса. Вернитесь к шагу Добавьте Resource ID частной конечной точки в список разрешённых для ваших сервисов.

Частная конечная точка находится в состоянии ожидания

Скорее всего, Resource ID частной конечной точки не был добавлен в список разрешённых для этого сервиса. Вернитесь к шагу Добавьте Resource ID частной конечной точки в список разрешённых для сервиса.

Проверка подключения

Если у вас возникают проблемы с подключением через Private Link, проверьте соединение с помощью openssl. Убедитесь, что статус конечной точки Private Link — Accepted. OpenSSL должен успешно подключаться (в выводе должно отображаться CONNECTED). errno=104 — ожидаемое значение.

openssl s_client -connect abcd.westus3.privatelink.azure.clickhouse.cloud:9440

CONNECTED(00000003)
write:errno=104
---
no peer certificate available
---
No client certificate CA names sent
---
SSL handshake has read 0 bytes and written 335 bytes
Verification: OK
---
New, (NONE), Cipher is (NONE)
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
Early data was not sent
Verify return code: 0 (ok)

Проверка фильтров для частной конечной точки

Установите следующие переменные среды перед запуском любых команд:

KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<please set ClickHouse organization ID>
INSTANCE_ID=<Instance ID>

Выполните следующую команду, чтобы проверить фильтры частной конечной точки:

curl --silent --user "${KEY_ID:?}:${KEY_SECRET:?}" -X GET -H "Content-Type: application/json" "https://api.clickhouse.cloud/v1/organizations/${ORG_ID:?}/services/${INSTANCE_ID:?}" | jq .result.privateEndpointIds

Дополнительная информация

Подробнее об Azure Private Link см. на azure.microsoft.com/en-us/products/private-link.

Последнее изменение 12 июня 2026 г.

Журналирование аудитаСтраница оглавления раздела журналирования аудита в ClickHouse Cloud

​Внимание

​Получите псевдоним подключения Azure для Private Link

​Вариант 1: консоль ClickHouse Cloud

​Вариант 2: API

​Создайте частную конечную точку в Azure

​Вариант 1: Использование Azure Portal для создания частной конечной точки в Azure

​Вариант 2: Создание частной конечной точки в Azure с помощью Terraform

​Получение Resource ID частной конечной точки

​Настройка DNS для Private Link

​Создание зоны Private DNS

​Создайте подстановочную DNS-запись

​Создайте связь с виртуальной сетью

​Проверьте настройку DNS

​Добавьте Resource ID частной конечной точки в организацию ClickHouse Cloud

​Вариант 1: консоль ClickHouse Cloud

​Вариант 2: API

​Добавьте Resource ID частной конечной точки в список разрешённых для ваших сервисов

​Вариант 1: консоль ClickHouse Cloud

​Вариант 2: API

​Доступ к вашему сервису ClickHouse Cloud через Private Link

​Получение имени хоста Private DNS

​Вариант 1: консоль ClickHouse Cloud

​Вариант 2: API

​Устранение неполадок

​Проверка настроек DNS

​Соединение сброшено удалённой стороной

​Частная конечная точка находится в состоянии ожидания

​Проверка подключения

​Проверка фильтров для частной конечной точки

​Дополнительная информация

Внимание

Получите псевдоним подключения Azure для Private Link

Вариант 1: консоль ClickHouse Cloud

Вариант 2: API

Создайте частную конечную точку в Azure

Вариант 1: Использование Azure Portal для создания частной конечной точки в Azure

Вариант 2: Создание частной конечной точки в Azure с помощью Terraform

Получение Resource ID частной конечной точки

Настройка DNS для Private Link

Создание зоны Private DNS

Создайте подстановочную DNS-запись

Создайте связь с виртуальной сетью

Проверьте настройку DNS

Добавьте Resource ID частной конечной точки в организацию ClickHouse Cloud

Вариант 1: консоль ClickHouse Cloud

Вариант 2: API

Добавьте Resource ID частной конечной точки в список разрешённых для ваших сервисов

Вариант 1: консоль ClickHouse Cloud

Вариант 2: API

Доступ к вашему сервису ClickHouse Cloud через Private Link

Получение имени хоста Private DNS

Вариант 1: консоль ClickHouse Cloud

Вариант 2: API

Устранение неполадок

Проверка настроек DNS

Соединение сброшено удалённой стороной

Частная конечная точка находится в состоянии ожидания

Проверка подключения

Проверка фильтров для частной конечной точки

Дополнительная информация