AWS PrivateLink

Scale plan feature

AWS PrivateLink is available in the Scale and Enterprise plans. To upgrade, visit the plans page in the cloud console.

Вы можете использовать AWS PrivateLink для организации защищённого подключения между VPC, сервисами AWS, локальными системами и ClickHouse Cloud, не выводя трафик в общедоступный интернет. В этом документе описаны шаги по подключению к ClickHouse Cloud с использованием AWS PrivateLink.

Чтобы ограничить доступ к вашим сервисам ClickHouse Cloud исключительно через адреса AWS PrivateLink, следуйте инструкциям из руководства ClickHouse Cloud IP Access Lists.

Примечание

ClickHouse Cloud поддерживает межрегиональный PrivateLink из следующих регионов:

sa-east-1
il-central-1
me-central-1
me-south-1
eu-central-2
eu-north-1
eu-south-2
eu-west-3
eu-south-1
eu-west-2
eu-west-1
eu-central-1
ca-west-1
ca-central-1
ap-northeast-1
ap-southeast-2
ap-southeast-1
ap-northeast-2
ap-northeast-3
ap-south-1
ap-southeast-4
ap-southeast-3
ap-south-2
ap-east-1
af-south-1
us-west-2
us-west-1
us-east-2
us-east-1 Особенности тарификации: AWS будет взимать плату с пользователей за передачу данных между регионами, см. цены здесь.

Выполните следующие шаги, чтобы включить AWS PrivateLink:

Получите «Service name» конечной точки (Endpoint).
Создайте AWS Endpoint.
Добавьте «Endpoint ID» в организацию ClickHouse Cloud.
Добавьте «Endpoint ID» в список разрешённых (allow list) для сервиса ClickHouse.

Примеры Terraform см. здесь.

Важные замечания

ClickHouse пытается группировать ваши сервисы, чтобы повторно использовать одну и ту же опубликованную конечную точку сервиса в пределах региона AWS. Однако такая группировка не гарантируется, особенно если вы распределяете свои сервисы между несколькими организациями ClickHouse. Если у вас уже настроен PrivateLink для других сервисов в вашей организации ClickHouse, во многих случаях вы можете пропустить большинство шагов благодаря такой группировке и перейти сразу к финальному шагу: добавьте «Endpoint ID» ClickHouse в список разрешённых для сервиса ClickHouse.

Предварительные требования для этого процесса

Перед началом вам потребуется:

Ваша учётная запись AWS.
API-ключ ClickHouse с необходимыми правами для создания и управления частными конечными точками на стороне ClickHouse.

Шаги

Следуйте этим шагам, чтобы подключить сервисы ClickHouse Cloud через AWS PrivateLink.

Получение значения параметра endpoint «Service name»

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

В консоли ClickHouse Cloud откройте сервис, который вы хотите подключить через PrivateLink, затем перейдите в меню Settings.

Запишите значения Service name и DNS name, затем перейдите к следующему шагу.

Вариант 2: API

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

REGION=<Код вашего региона в формате AWS, например: us-west-2>
PROVIDER=aws
KEY_ID=<Идентификатор ключа ClickHouse>
KEY_SECRET=<Секретный ключ ClickHouse>
ORG_ID=<Идентификатор организации ClickHouse>
SERVICE_NAME=<Имя сервиса ClickHouse>

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

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)

Получите значения параметров endpointServiceId и privateDnsHostname для конфигурации PrivateLink:

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

Эта команда должна вывести примерно следующее:

{
  "endpointServiceId": "com.amazonaws.vpce.us-west-2.vpce-svc-xxxxxxxxxxxxxxxxx",
  "privateDnsHostname": "xxxxxxxxxx.us-west-2.vpce.aws.clickhouse.cloud"
}

Запишите значения endpointServiceId и privateDnsHostname и перейдите к следующему шагу.

Создание AWS endpoint

Справочные материалы

В этом разделе описаны специфичные для ClickHouse детали настройки ClickHouse через AWS PrivateLink. Шаги, относящиеся к AWS, приведены как справочная информация, чтобы подсказать, где именно нужно проводить настройки, однако со временем они могут измениться без уведомления со стороны облачного провайдера AWS. Настраивайте конфигурацию AWS исходя из вашего конкретного сценария использования.

Обратите внимание, что ClickHouse не несет ответственности за настройку необходимых AWS VPC endpoint, правил групп безопасности (security groups) или DNS-записей.

Если вы ранее включали «private DNS names» при настройке PrivateLink и сейчас испытываете сложности с конфигурацией новых сервисов через PrivateLink, обратитесь в службу поддержки ClickHouse. По всем остальным вопросам, связанным с задачами конфигурации AWS, обращайтесь напрямую в службу поддержки AWS.

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

Откройте консоль AWS и перейдите в VPC → Endpoints → Create endpoints.

Выберите Endpoint services that use NLBs and GWLBs и используйте Service name^console или endpointServiceId^API, полученный на шаге Obtain Endpoint "Service name" , в поле Service Name. Нажмите Verify service:

Если вы хотите установить межрегиональное подключение через PrivateLink, установите флажок «Cross region endpoint» и укажите регион сервиса. Регион сервиса — это регион, в котором запущен экземпляр ClickHouse.

Если вы видите сообщение об ошибке «Service name could not be verified.», обратитесь в службу поддержки ClickHouse с запросом на добавление новых регионов в список поддерживаемых регионов.

Далее выберите ваш VPC и подсети:

Дополнительно при необходимости назначьте Security groups/Tags:

Примечание

Убедитесь, что порты 443, 8443, 9440, 3306 разрешены в группе безопасности (security group).

После создания VPC endpoint запишите значение Endpoint ID; оно понадобится вам на одном из следующих шагов.

Вариант 2: AWS CloudFormation

Далее необходимо создать VPC Endpoint, используя Service name^console или endpointServiceId^API, полученные на шаге Obtain Endpoint "Service name" . Убедитесь, что вы используете соответствующие идентификаторы подсетей (subnet IDs), группы безопасности (security groups) и идентификатор VPC (VPC ID).

Resources:
  ClickHouseInterfaceEndpoint:
    Type: 'AWS::EC2::VPCEndpoint'
    Properties:
      VpcEndpointType: Interface
      PrivateDnsEnabled: false
      ServiceName: <Имя сервиса (endpointServiceId), см. выше>
      VpcId: vpc-vpc_id
      SubnetIds:
        - subnet-subnet_id1
        - subnet-subnet_id2
        - subnet-subnet_id3
      SecurityGroupIds:
        - sg-security_group_id1
        - sg-security_group_id2
        - sg-security_group_id3

После создания VPC Endpoint запишите значение Endpoint ID — оно понадобится на одном из следующих шагов.

Вариант 3: Terraform

service_name ниже — это Service name^console или endpointServiceId^API, полученное на шаге Obtain Endpoint "Service name" .

resource "aws_vpc_endpoint" "this" {
  vpc_id            = var.vpc_id
  service_name      = "<pls see comment above>"
  vpc_endpoint_type = "Interface"
  security_group_ids = [
    Var.security_group_id1,var.security_group_id2, var.security_group_id3,
  ]
  subnet_ids          = [var.subnet_id1,var.subnet_id2,var.subnet_id3]
  private_dns_enabled = false
  service_region      = "(Необязательно) Если указан, конечная точка VPC будет подключаться к сервису в указанном регионе. Укажите это значение для мультирегиональных соединений PrivateLink."
}

После создания VPC Endpoint запишите значение Endpoint ID — оно понадобится на одном из следующих шагов.

Настройка приватного DNS-имени для endpoint

Примечание

Существует несколько способов настройки DNS. Настройте DNS в соответствии с вашим конкретным вариантом использования.

Вам нужно привязать «DNS name», полученное на шаге Obtain Endpoint "Service name" , к сетевым интерфейсам AWS Endpoint. Это обеспечит корректное разрешение имени сервисами и компонентами внутри вашей VPC/сети.

Добавление «Endpoint ID» в список разрешённых для сервиса ClickHouse

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

Чтобы добавить endpoint, перейдите в консоль ClickHouse Cloud, откройте сервис, который вы хотите подключить через PrivateLink, затем перейдите в раздел Settings. Нажмите Set up private endpoint, чтобы открыть настройки private endpoints. Введите Endpoint ID, полученный на шаге Create AWS Endpoint. Нажмите «Create endpoint».

Примечание

Если вы хотите разрешить доступ из уже существующего соединения PrivateLink, используйте существующий endpoint в выпадающем меню.

Чтобы удалить endpoint, перейдите в консоль ClickHouse Cloud, найдите нужный сервис, затем перейдите в Settings этого сервиса, найдите endpoint, который вы хотите удалить, и удалите его из списка endpoints.

Вариант 2: API

Вам нужно добавить Endpoint ID в allow-list для каждого экземпляра, который должен быть доступен через PrivateLink.

Установите переменную окружения ENDPOINT_ID, используя данные с шага Create AWS Endpoint.

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

REGION=<Код региона в формате AWS, например: us-west-2>
PROVIDER=aws
KEY_ID=<ID ключа ClickHouse>
KEY_SECRET=<Секретный ключ ClickHouse>
ORG_ID=<ID организации ClickHouse>
SERVICE_NAME=<Имя сервиса ClickHouse>

Чтобы добавить идентификатор конечной точки в список разрешённых:

cat <<EOF | tee pl_config.json
{
  "privateEndpointIds": {
    "add": [
      "${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

Чтобы удалить идентификатор конечной точки из списка разрешённых конечных точек:

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

Доступ к экземпляру с использованием PrivateLink

Каждый сервис с включённым Private Link имеет публичную и приватную конечные точки. Для подключения через Private Link необходимо использовать приватную конечную точку — это будет privateDnsHostname^API или DNS Name^console, полученные из раздела Obtain Endpoint "Service name".

Получение приватного DNS-имени хоста

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

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

Вариант 2: API

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

KEY_ID=<Ваш ID ключа ClickHouse>
KEY_SECRET=<Ваш секретный ключ ClickHouse>
ORG_ID=<ID вашей организации ClickHouse>
INSTANCE_ID=<Имя вашего сервиса ClickHouse>

Вы можете получить INSTANCE_ID на этом шаге.

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

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

{
  "endpointServiceId": "com.amazonaws.vpce.us-west-2.vpce-svc-xxxxxxxxxxxxxxxxx",
  "privateDnsHostname": "xxxxxxxxxx.us-west-2.vpce.aws.clickhouse.cloud"
}

В этом примере соединение по имени хоста со значением privateDnsHostname будет маршрутизировано через PrivateLink, а соединение по имени хоста со значением endpointServiceId — через интернет.

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

Несколько PrivateLink в одном регионе

В большинстве случаев вам нужно создать только один endpoint service для каждого VPC. Этот endpoint может направлять запросы из VPC к нескольким сервисам ClickHouse Cloud. См. здесь

Таймаут при подключении к приватному endpoint

Привяжите группу безопасности (security group) к VPC Endpoint.
Проверьте правила inbound у группы безопасности, привязанной к Endpoint, и разрешите порты ClickHouse.
Проверьте правила outbound у группы безопасности, привязанной к VM, которая используется для проверки подключения, и разрешите подключения к портам ClickHouse.

Приватное имя хоста: адрес хоста не найден

Проверьте конфигурацию DNS.

Connection reset by peer

Скорее всего, Endpoint ID не был добавлен в список разрешённых (allow list) сервиса, перейдите к шагу

Проверка фильтров endpoint

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

KEY_ID=<ID ключа>
KEY_SECRET=<Секретный ключ>
ORG_ID=<укажите ID организации ClickHouse>
INSTANCE_ID=<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

Подключение к удалённой базе данных

Предположим, вы пытаетесь использовать табличные функции MySQL или PostgreSQL в ClickHouse Cloud и подключиться к своей базе данных, размещённой в VPC Amazon Web Services (AWS). AWS PrivateLink нельзя использовать для безопасной организации такого подключения. PrivateLink — это одностороннее (unidirectional) соединение. Оно позволяет вашей внутренней сети или Amazon VPC безопасно подключаться к ClickHouse Cloud, но не позволяет ClickHouse Cloud подключаться к вашей внутренней сети.

Согласно документации AWS PrivateLink:

Используйте AWS PrivateLink, когда у вас есть клиент-серверная архитектура и вы хотите разрешить одному или нескольким VPC-потребителям односторонний доступ к определённому сервису или набору экземпляров в VPC-поставщика сервиса. Только клиенты в VPC-потребителе могут инициировать подключение к сервису в VPC-поставщика.

Для этого настройте AWS Security Groups так, чтобы они разрешали подключения от ClickHouse Cloud к вашему внутреннему/частному сервису базы данных. Ознакомьтесь с IP-адресами исходящего трафика по умолчанию для регионов ClickHouse Cloud, а также с доступными статическими IP-адресами.

Важные замечания​

Предварительные требования для этого процесса​

Шаги​

Получение значения параметра endpoint «Service name»​

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

Вариант 2: API​

Создание AWS endpoint​

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

Вариант 2: AWS CloudFormation​

Вариант 3: Terraform​

Настройка приватного DNS-имени для endpoint​

Добавление «Endpoint ID» в список разрешённых для сервиса ClickHouse​

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

Вариант 2: API​

Доступ к экземпляру с использованием PrivateLink​

Получение приватного DNS-имени хоста​

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

Вариант 2: API​

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

Несколько PrivateLink в одном регионе​

Таймаут при подключении к приватному endpoint​

Приватное имя хоста: адрес хоста не найден​

Connection reset by peer​

Проверка фильтров endpoint​

Подключение к удалённой базе данных​

Важные замечания

Предварительные требования для этого процесса

Шаги

Получение значения параметра endpoint «Service name»

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

Вариант 2: API

Создание AWS endpoint

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

Вариант 2: AWS CloudFormation

Вариант 3: Terraform

Настройка приватного DNS-имени для endpoint

Добавление «Endpoint ID» в список разрешённых для сервиса ClickHouse

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

Вариант 2: API

Доступ к экземпляру с использованием PrivateLink

Получение приватного DNS-имени хоста

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

Вариант 2: API

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

Несколько PrivateLink в одном регионе

Таймаут при подключении к приватному endpoint

Приватное имя хоста: адрес хоста не найден

Connection reset by peer

Проверка фильтров endpoint

Подключение к удалённой базе данных