AWS PrivateLink

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

AWS PrivateLink поддерживает только подключения, инициированные из вашего AWS VPC к ClickHouse Cloud. Его нельзя использовать для подключений, инициированных из ClickHouse Cloud к сервисам в вашем VPC, таким как private database.

Чтобы ограничить доступ к вашим сервисам ClickHouse Cloud только адресами AWS PrivateLink, следуйте инструкциям ClickHouse Cloud по IP Access Lists. ClickHouse Cloud поддерживает межрегиональный PrivateLink для сервисов, размещённых в следующих регионах AWS: Таблица охватывает только регионы размещения сервисов. Для регионов интерфейсных VPC endpoint потребителей используется отдельный список разрешённых; например, mx-central-1 является разрешённым регионом потребителя, хотя сервисы, размещённые в нём, не могут включить межрегиональный доступ.

Код региона	Название региона
`af-south-1`	Африка (Кейптаун)
`ap-east-1`	Азиатско-Тихоокеанский регион (Гонконг)
`ap-northeast-1`	Азиатско-Тихоокеанский регион (Токио)
`ap-northeast-2`	Азиатско-Тихоокеанский регион (Сеул)
`ap-south-1`	Азиатско-Тихоокеанский регион (Мумбаи)
`ap-southeast-1`	Азиатско-Тихоокеанский регион (Сингапур)
`ap-southeast-2`	Азиатско-Тихоокеанский регион (Сидней)
`ap-southeast-3`	Азиатско-Тихоокеанский регион (Джакарта)
`ap-southeast-5`	Азиатско-Тихоокеанский регион (Малайзия)
`ca-central-1`	Канада (Центральный)
`eu-central-1`	Европа (Франкфурт)
`eu-north-1`	Европа (Стокгольм)
`eu-west-1`	Европа (Ирландия)
`eu-west-2`	Европа (Лондон)
`il-central-1`	Израиль (Тель-Авив)
`me-central-1`	Ближний Восток (ОАЭ)
`sa-east-1`	Южная Америка (Сан-Паулу)
`us-east-1`	Восток США (N. Virginia)
`us-east-2`	Восток США (Огайо)
`us-west-2`	Запад США (Орегон)

Межрегиональный PrivateLink не поддерживается для сервисов ClickHouse Cloud, размещённых в ap-east-2 или mx-central-1. Чтобы подключиться к сервису в любом из этих регионов с помощью PrivateLink, создайте интерфейсный VPC endpoint в том же регионе AWS, что и сервис.

AWS взимает плату за межрегиональную передачу данных. Подробнее см. в разделе тарифы AWS PrivateLink.

Чтобы включить AWS PrivateLink, выполните следующие действия:

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

Примеры Terraform можно найти здесь.

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

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

Необходимые условия для этого процесса

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

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

Шаги

Чтобы подключить сервисы ClickHouse Cloud через AWS PrivateLink, выполните следующие шаги.

Получение значения «Service name» для конечной точки

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

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

Вариант 2: API

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

REGION=<Your region code using the AWS format, for example: us-west-2>
PROVIDER=aws
KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
SERVICE_NAME=<Your ClickHouse service name>

Получите INSTANCE_ID ClickHouse, отфильтровав по региону, провайдеру и 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)

Получите 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 через AWS PrivateLink, относящиеся именно к ClickHouse. Шаги, относящиеся к AWS, приведены в качестве справочной информации, чтобы подсказать, где искать нужные параметры, однако со временем они могут измениться без предварительного уведомления со стороны AWS. Выполняйте настройку AWS с учетом вашего конкретного сценария использования.Обратите внимание, что ClickHouse не отвечает за настройку необходимых конечных точек AWS VPC, правил Security Group или DNS-записей.Если при настройке PrivateLink вы ранее включили “private DNS names” и теперь испытываете трудности с настройкой новых сервисов через PrivateLink, обратитесь в службу поддержки ClickHouse. По всем остальным вопросам, связанным с настройкой AWS, обращайтесь напрямую в AWS Support.

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

Откройте консоль AWS и перейдите в VPC → Endpoints → Create endpoints. Выберите Endpoint services that use NLBs and GWLBs и в поле Service Name укажите Service name^{консоль} или endpointServiceId^API, полученные на шаге получения значения «Service name» для конечной точки . Нажмите Verify service:

Для межрегионального подключения установите флажок Cross region endpoint и укажите регион сервиса, в котором запущен ваш сервис ClickHouse.

Если возникнет ошибка “Service name couldn’t be verified.”, обратитесь в службу поддержки с запросом на добавление новых регионов в список поддерживаемых регионов. Затем выберите VPC и подсети: При необходимости назначьте группы безопасности и теги:

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

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

Вариант 2: AWS CloudFormation

Далее вам нужно создать конечную точку VPC, используя Service name^{консоль} или endpointServiceId^API, полученные на шаге получения значения «Service name» для конечной точки . Убедитесь, что используете правильные идентификаторы подсетей, групп безопасности и VPC.

Resources:
  ClickHouseInterfaceEndpoint:
    Type: 'AWS::EC2::VPCEndpoint'
    Properties:
      VpcEndpointType: Interface
      PrivateDnsEnabled: false
      ServiceName: <Service name(endpointServiceId), pls see above>
      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 ID; оно понадобится на одном из следующих шагов.

Вариант 3: Terraform

service_name ниже — это Service name^{консоль} или endpointServiceId^API, полученные на шаге получения значения «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      = "(Optional) If specified, the VPC endpoint will connect to the service in the provided region. Define it for multi-regional PrivateLink connections."
}

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

Настройте частное DNS-имя для конечной точки

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

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

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

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

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

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

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

Вариант 2: API

Вам нужно добавить Endpoint ID в список разрешённых для каждого экземпляра, который должен быть доступен через PrivateLink. Задайте переменную окружения ENDPOINT_ID, используя данные из шага создание AWS endpoint. Перед выполнением каких-либо команд задайте следующие переменные окружения:

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

Чтобы добавить Endpoint ID в список разрешенных:

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

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

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 из шага получение значения «Service name» для конечной точки.

Получение частного DNS-имени

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

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

Вариант 2: API

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

KEY_ID=<Your ClickHouse key ID>
KEY_SECRET=<Your ClickHouse key secret>
ORG_ID=<Your ClickHouse organization ID>
INSTANCE_ID=<Your ClickHouse service name>

Вы можете получить 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 в одном регионе

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

Время ожидания подключения к частной конечной точке истекло

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

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

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

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

Скорее всего, Endpoint ID не был добавлен в список разрешённых для сервиса; см. шаг

Проверка фильтров конечных точек

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

KEY_ID=<Key ID>
KEY_SECRET=<Key secret>
ORG_ID=<please set ClickHouse organization ID>
INSTANCE_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

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

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

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

Чтобы подключить табличные функции MySQL или PostgreSQL в ClickHouse Cloud к базе данных, размещённой в вашей AWS VPC, настройте группы безопасности AWS так, чтобы разрешить подключения из ClickHouse Cloud. См. IP-адреса egress по умолчанию для регионов ClickHouse Cloud, а также доступные статические IP-адреса.

Get started

Services and infrastructure

Bring Your Own Cloud

Data and integrations

Connect and query

Access management

Security and compliance

Monitoring and backups

AI tools and agents

Cloud API

Billing

Support

ClickHouse Private

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

Необходимые условия для этого процесса

Шаги

Получение значения «Service name» для конечной точки

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

Вариант 2: API

Создание AWS endpoint

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

Вариант 2: AWS CloudFormation

Вариант 3: Terraform

Настройте частное DNS-имя для конечной точки

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

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

Вариант 2: API

Доступ к экземпляру через PrivateLink

Получение частного DNS-имени

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

Вариант 2: API

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

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

​Необходимые условия для этого процесса

​Шаги

​Получение значения «Service name» для конечной точки

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

​Вариант 2: API

​Создание AWS endpoint

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

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

​Вариант 3: Terraform

​Настройте частное DNS-имя для конечной точки

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

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

​Вариант 2: API

​Доступ к экземпляру через PrivateLink

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

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

Вариант 2: API

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

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

Необходимые условия для этого процесса

Шаги

Получение значения «Service name» для конечной точки

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

Вариант 2: API

Создание AWS endpoint

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

Вариант 2: AWS CloudFormation

Вариант 3: Terraform

Настройте частное DNS-имя для конечной точки

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

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

Вариант 2: API

Доступ к экземпляру через PrivateLink

Получение частного DNS-имени

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