Подключение к управляемым БД из функции Cloud Functions через пользовательскую сеть VPC
С помощью этого руководства вы создадите функцию Cloud Functions на Python, которая подключается к приватной базе данных Managed Service for PostgreSQL или Managed Service for ClickHouse® через пользовательскую сеть и выполняет запрос SELECT 1.
Функция подключается к кластеру через хост в пользовательской сети. Для аутентификации в кластере можно использовать IAM-токен сервисного аккаунта или пароль из Yandex Lockbox.
Чтобы создать функцию и подключиться к управляемой БД:
- Подготовьте облако к работе.
- Подготовьте кластер и сеть.
- Создайте сервисный аккаунт.
- Настройте аутентификацию.
- Подготовьте код функции.
- Создайте функцию.
- Вызовите функцию.
Если созданные ресурсы вам больше не нужны, удалите их.
Подготовьте облако к работе
Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:
- Перейдите в консоль управления
, затем войдите в Yandex Cloud или зарегистрируйтесь. - На странице Yandex Cloud Billing
убедитесь, что у вас подключен платежный аккаунт, и он находится в статусеACTIVEилиTRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.
Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака
Подробнее об облаках и каталогах.
Для выполнения команд из руководства установите и настройте следующие инструменты:
- Yandex Cloud CLI.
bash,curl,jq.zip— для упаковки кода функции в архив.
Необходимые платные ресурсы
В стоимость поддержки инфраструктуры для этого руководства входит:
- плата за вычислительные ресурсы кластера, объем хранилища и резервных копий (тарифы Managed Service for PostgreSQL или Managed Service for ClickHouse®);
- плата за количество вызовов функции и вычислительные ресурсы, выделенные для ее выполнения (тарифы Yandex Cloud Functions);
- плата за хранение секретов, если для аутентификации используется пароль (тарифы Yandex Lockbox).
Подготовьте кластер и сеть
Для подключения из функции кластеру нужна сеть с подсетями во всех зонах доступности и хотя бы один ресурс с IP-адресом в этой сети. Хост приватного кластера подходит в качестве такого ресурса.
-
Если у вас еще нет подходящего кластера, создайте его: Managed Service for PostgreSQL или Managed Service for ClickHouse®. Публичный доступ к хостам кластера можно оставить выключенным.
-
В консоли управления
выберите каталог с кластером и откройте его страницу. -
В разделе Обзор проверьте, что в сети кластера есть подсети во всех зонах доступности.
-
Добавьте в группу безопасности кластера правило для входящего трафика со следующими параметрами:
- Протокол —
TCP. - Источник —
Диапазон адресов. - IPv4 CIDR —
198.19.0.0/16. Это диапазон служебных подсетей, из которых функция обращается к ресурсам в пользовательской сети. - Диапазон портов —
6432для PostgreSQL или8443для ClickHouse®.
- Протокол —
-
На странице кластера откройте раздел Хосты и скопируйте значение в столбце FQDN хоста. Для PostgreSQL выберите хост-мастер.
-
В разделе Базы данных скопируйте имя нужной базы данных.
Сохраните параметры кластера в переменных текущей Bash-сессии. В переменной DB_HOST укажите только FQDN, без схемы, порта и пути. Выберите одно значение для DB_ENGINE.
DB_ENGINE='postgresql' # Для ClickHouse® укажите clickhouse.
CLUSTER_ID='<идентификатор_кластера>'
DB_HOST='<FQDN_хоста>'
DB_NAME='<имя_БД>'
MDB_SERVICE="managed-${DB_ENGINE}"
NETWORK_ID=$(yc "$MDB_SERVICE" cluster get --id "$CLUSTER_ID" --format json |
jq -er .network_id)
Чтобы сверить FQDN и имя базы через CLI, выполните команды. В выводе host list адрес находится в столбце NAME:
yc "$MDB_SERVICE" host list --cluster-id "$CLUSTER_ID"
yc "$MDB_SERVICE" database list --cluster-id "$CLUSTER_ID"
Примечание
Если приложение выполняет запись в многохостовый кластер PostgreSQL, используйте FQDN текущего мастера или несколько FQDN с выбором доступного для записи хоста.
Создайте сервисный аккаунт
Создайте сервисный аккаунт, от имени которого будет работать функция, и сохраните его идентификатор в переменной SA_ID:
SA_NAME='private-db-example-sa'
SA_ID=$(yc iam service-account create --name "$SA_NAME" --format json |
jq -er .id)
Если сервисный аккаунт уже существует в текущем каталоге, подставьте его имя и получите идентификатор командой get:
SA_NAME='<имя_сервисного_аккаунта>'
SA_ID=$(yc iam service-account get --name "$SA_NAME" --format json |
jq -er .id)
Примечание
Для создания сервисного аккаунта и развертывания функции нужны соответствующие права в текущем каталоге. Если при развертывании не хватает права на использование сервисного аккаунта, нужно выдать роль iam.serviceAccounts.user на сам созданный сервисный аккаунт.
Настройте аутентификацию
Выберите способ аутентификации в кластере и выполните команды в той же Bash-сессии.
Функция запрашивает IAM-токен сервисного аккаунта из сервиса метаданных и использует его как пароль к БД.
-
Создайте в кластере пользователя с именем, равным идентификатору сервисного аккаунта:
if [[ "$DB_ENGINE" == postgresql ]]; then yc managed-postgresql user create "$SA_ID" --cluster-id "$CLUSTER_ID" \ --auth-method auth-method-iam --permissions "$DB_NAME" --login else yc managed-clickhouse user create "$SA_ID" --cluster-id "$CLUSTER_ID" \ --auth-method iam --permissions "$DB_NAME" fi -
Назначьте сервисному аккаунту роль для подключения к кластеру:
yc "$MDB_SERVICE" cluster add-access-binding --id "$CLUSTER_ID" \ --role "$MDB_SERVICE.clusters.connector" --service-account-id "$SA_ID" -
Разрешите сервисному аккаунту получать собственный IAM-токен:
yc iam service-account add-access-binding --id "$SA_ID" \ --role iam.serviceAccounts.user --service-account-id "$SA_ID" -
Сохраните параметры для команды создания версии функции:
AUTH_ARGS=(--environment "DB_AUTH=iam,DB_USER=$SA_ID")
Примечание
Для рабочего приложения выдайте пользователю БД права на нужные SQL-операции.
Функция получает имя и пароль пользователя БД из секрета Yandex Lockbox через переменные окружения.
-
Создайте в кластере пользователя с парольной аутентификацией и доступом к выбранной БД или используйте существующего. В консоли откройте кластер и перейдите в раздел Пользователи.
-
Создайте секрет Yandex Lockbox с двумя текстовыми ключами:
username— имя пользователя БД;password— его пароль.
Скопируйте идентификатор секрета и идентификатор его версии.
-
Сохраните идентификаторы в переменных:
SECRET_ID='<идентификатор_секрета>' SECRET_VERSION_ID='<идентификатор_версии_секрета>' -
Выдайте сервисному аккаунту доступ к секрету:
yc lockbox secret add-access-binding --id "$SECRET_ID" \ --role lockbox.payloadViewer --service-account-id "$SA_ID"Если секрет зашифрован пользовательским ключом Key Management Service, дополнительно выдайте сервисному аккаунту роль
kms.keys.encrypterDecrypterна ключ. -
Сохраните параметры для команды создания версии функции:
AUTH_ARGS=( --environment DB_AUTH=password --secret "environment-variable=DB_USER,id=$SECRET_ID,version-id=$SECRET_VERSION_ID,key=username" --secret "environment-variable=DB_PASSWORD,id=$SECRET_ID,version-id=$SECRET_VERSION_ID,key=password" )
Примечание
Передача секретов в окружение функции находится на стадии Preview. При смене версии секрета повторно создайте версию функции с новым значением SECRET_VERSION_ID.
Подготовьте код функции
Среда выполнения Python 3.12 в Cloud Functions уже содержит CA-сертификат для управляемых БД по пути /usr/local/share/ca-certificates/yandex-internal-ca.crt. Функция использует его для проверки TLS-соединения.
-
Создайте пустой рабочий каталог и перейдите в него.
-
Создайте файл
requirements.txtсо списком зависимостей:psycopg2-binary==2.9.10 -
Создайте файл
db.py. Код подключается к выбранной СУБД, проверяет сертификат и имя сервера, выполняет запросSELECT 1и закрывает соединение.import json import os import ssl from contextlib import closing from http.client import HTTPConnection, HTTPSConnection from urllib.parse import urlencode CA = "/usr/local/share/ca-certificates/yandex-internal-ca.crt" def credentials(): user = os.environ["DB_USER"] if os.environ["DB_AUTH"] == "password": return user, os.environ["DB_PASSWORD"] with closing(HTTPConnection("169.254.169.254", timeout=3)) as metadata: metadata.request( "GET", "/computeMetadata/v1/instance/service-accounts/default/token", headers={"Metadata-Flavor": "Google"}, ) with metadata.getresponse() as response: if response.status != 200: raise RuntimeError(f"Metadata HTTP {response.status}") return user, json.load(response)["access_token"] def select_one(): engine = os.environ["DB_ENGINE"] if engine not in {"postgresql", "clickhouse"}: raise ValueError("DB_ENGINE must be postgresql or clickhouse") host = os.environ["DB_HOST"] database = os.environ["DB_NAME"] user, password = credentials() if engine == "postgresql": import psycopg2 with closing(psycopg2.connect( host=host, port=6432, dbname=database, user=user, password=password, connect_timeout=5, sslmode="verify-full", sslrootcert=CA, options="-c statement_timeout=5000", )) as connection, connection.cursor() as cursor: cursor.execute("SELECT 1") return cursor.fetchone()[0] tls = ssl.create_default_context(cafile=CA) path = "/?" + urlencode({"database": database}) with closing(HTTPSConnection(host, 8443, timeout=5, context=tls)) as connection: connection.request( "POST", path, body=b"SELECT 1", headers={"X-ClickHouse-User": user, "X-ClickHouse-Key": password}, ) with connection.getresponse() as response: if response.status != 200: raise RuntimeError(f"ClickHouse HTTP {response.status}") return int(response.read()) -
Создайте файл
index.pyс обработчиком функции:import json from db import select_one def handler(event, context): return { "statusCode": 200, "headers": {"Content-Type": "application/json"}, "body": json.dumps({"result": select_one()}), } -
Упакуйте файлы в ZIP-архив. Они должны лежать в корне архива:
zip function.zip index.py db.py requirements.txt
Создайте функцию
-
В консоли управления
выберите каталог, в котором нужно создать функцию. -
Перейдите
в сервис Cloud Functions. -
Нажмите кнопку Создать функцию.
-
Введите имя функции и нажмите Создать.
-
В блоке Редактор выберите среду выполнения
Python 3.12и отключите опцию Добавить файлы с примерами кода. -
В блоке Код функции выберите способ
ZIP-архиви загрузите подготовленный ранее ZIP-архив. -
В качестве точки входа укажите
index.handler. -
В блоке с параметрами задайте:
- сервисный аккаунт, созданный ранее;
- сеть кластера Managed Service for PostgreSQL или Managed Service for ClickHouse®;
- переменные окружения
DB_ENGINE,DB_HOST,DB_NAMEиDB_AUTHсо значениями из предыдущих шагов. Для аутентификации по IAM-токену добавьте также переменнуюDB_USERсо значением идентификатора сервисного аккаунта.
-
Для аутентификации по паролю в блоке с секретами Yandex Lockbox добавьте две привязки для переменных
DB_USERиDB_PASSWORDс ключамиusernameиpasswordиз подготовленного секрета. -
Нажмите кнопку Сохранить изменения.
-
Укажите имя функции в текущем каталоге:
FUNCTION_NAME='private-db-example' -
Создайте функцию:
yc serverless function create --name "$FUNCTION_NAME" -
Создайте версию функции. Команда загрузит архив, подключит функцию к сети кластера и применит выбранный способ аутентификации:
yc serverless function version create --function-name "$FUNCTION_NAME" \ --runtime python312 --entrypoint index.handler \ --memory 256MB --execution-timeout 20s --source-path function.zip \ --network-id "$NETWORK_ID" --service-account-id "$SA_ID" \ --environment "DB_ENGINE=$DB_ENGINE,DB_HOST=$DB_HOST,DB_NAME=$DB_NAME" \ "${AUTH_ARGS[@]}"
Вызовите функцию
Для вызова функции у вашего аккаунта должна быть роль functions.functionInvoker или другая роль, дающая право вызывать функции.
Вызовите функцию:
yc serverless function invoke --name "$FUNCTION_NAME" --data '{}'
Ожидаемый результат:
{"statusCode":200,"headers":{"Content-Type":"application/json"},"body":"{\"result\": 1}"}
Значение result: 1 означает, что функция подключилась к БД, прошла аутентификацию и получила результат SQL-запроса.
При ошибке подключения проверьте:
- логи функции;
- выбранную сеть;
- правило группы безопасности;
- настройки пользователя БД.
Как удалить созданные ресурсы
Чтобы перестать платить за созданные ресурсы:
- Удалите функцию.
- Удалите кластер Managed Service for PostgreSQL или кластер Managed Service for ClickHouse®, если он больше не нужен.
- Если для аутентификации использовался пароль, удалите секрет Yandex Lockbox.
- Удалите сервисный аккаунт, если он больше не нужен.