Подключение к базе данных Yandex Managed Service for YDB из функции Cloud Functions на Node.js
Примечание
Руководство предназначено для пользователей Linux. На Windows пройти руководство можно в среде WSL.
Вы создадите функцию с приложением на Node.js, которое выполняет простой запрос к базе данных YDB. Развертывание приложения осуществляется с помощью Bash-скриптов, для компиляции используется команда tcs
.
Функция с привязанным сервисным аккаунтом авторизуется в YDB через сервис метаданных.
Приложение создает драйвер подключения к базе YDB, сессию, транзакцию и выполняет запрос, используя библиотеку ydb
. Эта библиотека устанавливается как зависимость при создании версии функции. Параметры подключения к базе данных передаются в приложение через переменные окружения.
Чтобы настроить подключение к базе данных YDB:
- Подготовьте облако к работе.
- Подготовьте окружение.
- Создайте сервисный аккаунт.
- Создайте авторизованный ключ.
- Создайте базу данных YDB.
- Создайте функцию.
- Протестируйте функцию.
Если созданные ресурсы вам больше не нужны, удалите их.
Подготовьте облако к работе
Перед работой нужно зарегистрироваться в Yandex Cloud и создать платежный аккаунт:
- Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь, если вы еще не зарегистрированы.
- На странице биллинга убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе
ACTIVE
илиTRIAL_ACTIVE
. Если платежного аккаунта нет, создайте его.
Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.
Подробнее об облаках и каталогах.
Необходимые платные ресурсы
В стоимость поддержки инфраструктуры для этого сценария входит:
- плата за использование функции (см. тарифы Yandex Cloud Functions);
- плата за выполнение запросов к базе данных (см. тарифы Yandex Managed Service for YDB).
Подготовьте окружение
-
Клонируйте репозиторий examples с помощью Git:
git clone https://github.com/ydb-platform/ydb-nodejs-sdk.git
-
В репозитории перейдите в папку с файлами проекта:
examples/basic-example-v1
. -
Установите и инициализируйте интерфейс командной строки Yandex Cloud.
-
Установите утилиту jq. В корне папки с файлами проекта запустите терминал и выполните команду:
sudo apt-get install jq
-
Установите Node.js, выполнив команду:
curl -fsSL https://deb.nodesource.com/setup_current.x | sudo -E bash - \ sudo apt-get install -y nodejs
-
Установите зависимости, выполнив команду:
npm install
Создайте сервисный аккаунт
- В консоли управления выберите каталог, в котором хотите создать сервисный аккаунт.
- Выберите вкладку Сервисные аккаунты.
- Нажмите кнопку Создать сервисный аккаунт.
- Введите имя сервисного аккаунта:
sa-function
. - Нажмите Добавить роль и выберите
editor
. - Нажмите кнопку Создать.
Выполните команду:
yc iam service-account create --name sa-function
Подробнее о команде yc iam service-account create
см. в справочнике CLI.
Если у вас ещё нет Terraform, установите его и настройте провайдер Yandex Cloud.
-
Опишите в конфигурационном файле параметры сервисного аккаунта:
resource "yandex_iam_service_account" "sa" { name = "sa-function" }
Более подробную информацию о ресурсах, которые вы можете создать с помощью Terraform, см. в документации провайдера.
-
Проверьте корректность конфигурационных файлов.
-
В командной строке перейдите в папку, где вы создали конфигурационный файл.
-
Выполните проверку с помощью команды:
terraform plan
Если конфигурация описана верно, в терминале отобразится список создаваемых ресурсов и их параметров. Если в конфигурации есть ошибки, Terraform на них укажет.
-
-
Разверните облачные ресурсы.
-
Если в конфигурации нет ошибок, выполните команду:
terraform apply
-
Подтвердите создание ресурсов: введите в терминал слово
yes
и нажмите Enter.
-
Чтобы создать сервисный аккаунт, воспользуйтесь методом create для ресурса ServiceAccount.
Создайте авторизованный ключ
-
В консоли управления выберите каталог, которому принадлежит сервисный аккаунт.
-
Перейдите на вкладку Сервисные аккаунты.
-
Выберите сервисный аккаунт
sa-function
и нажмите на строку с его именем. -
Нажмите кнопку Создать новый ключ на верхней панели.
-
Выберите пункт Создать авторизованный ключ.
-
Выберите алгоритм шифрования.
-
Задайте описание ключа, чтобы потом было проще найти его в консоли управления.
-
Сохраните открытый и закрытый ключи в файл
service_account_key_file.json
:{ "service_account_id": "<идентификатор сервисного аккаунта sa-function>", "key_algorithm": "RSA_2048", "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----\n", "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n" }
Выполните команду:
yc iam key create --service-account-name sa-function -o service_account_key_file.json
Подробнее о команде yc iam key create
см. в справочнике CLI.
В случае успеха в файл service_account_key_file.json
будет записан закрытый ключ (privateKey
) и идентификатор открытого ключа (id
).
-
Опишите в конфигурационном файле параметры ключа:
resource "yandex_iam_service_account_key" "sa-auth-key" { service_account_id = "<идентификатор сервисного аккаунта sa-function>" key_algorithm = "RSA_2048" }
Более подробную информацию о ресурсах, которые вы можете создать с помощью Terraform, см. в документации провайдера.
-
Проверьте корректность конфигурационных файлов.
-
В командной строке перейдите в папку, где вы создали конфигурационный файл.
-
Выполните проверку с помощью команды:
terraform plan
Если конфигурация описана верно, в терминале отобразится список создаваемых ресурсов и их параметров. Если в конфигурации есть ошибки, Terraform на них укажет.
-
-
Разверните облачные ресурсы.
-
Если в конфигурации нет ошибок, выполните команду:
terraform apply
-
Подтвердите создание ресурсов: введите в терминал слово
yes
и нажмите Enter.
-
Создайте базу данных YDB
-
В консоли управления выберите каталог, в котором хотите создать базу данных.
-
В списке сервисов выберите Managed Service for YDB.
-
Нажмите кнопку Создать базу данных.
-
Введите имя базы. Требования к имени:
- Длина — от 3 до 63 символов.
- Может содержать строчные буквы латинского алфавита, цифры и дефисы.
- Первый символ — буква. Последний символ — не дефис.
-
В блоке Тип базы данных выберите опцию Serverless.
-
Нажмите кнопку Создать базу данных.
Дождитесь запуска базы данных. В процессе создания база будет иметь статус
Provisioning
. Когда база станет готова к использованию, статус сменится наRunning
. -
Нажмите на имя созданной БД.
-
Сохраните значения полей Эндпоинт и Размещение базы данных из блока Соединение. Они понадобятся на следующем шаге.
Создайте функцию
Примечание
Перед созданием функции убедитесь, что в файле .env
и файлах create-func.sh
и create-func-ver.sh
из папки deploy
в качестве символа перевода строки установлен LF
.
-
Отредактируйте файл
.env
:ENDPOINT
— строка вида <протокол>://<значение поля Эндпоинт из блока Соединение>. Например, если протоколgrpcs
, а эндпоинтydb.serverless.yandexcloud.net:2135
, введитеgrpcs://ydb.serverless.yandexcloud.net:2135
.DATABASE
— значение поля Размещение базы данных из блока Соединение.FUNCTION_NAME
— имя функции:func-test-ydb
.FOLDER_ID
— идентификатор каталога.SERVICE_ACCOUNT_ID
— идентификатор сервисного аккаунтаsa-function
.
-
В корне проекта запустите командную строку и выполните команду:
./deploy/create-func.sh
Этот скрипт создает новую функцию в вашем каталоге и делает ее публичной.
-
Создайте версию функции:
./deploy/create-func-ver.sh
Протестируйте функцию
-
В консоли управления выберите каталог, в котором находится функция.
-
В списке сервисов выберите Cloud Functions.
-
Выберите функцию
func-test-ydb
. -
Перейдите на вкладку Обзор.
-
В блоке Общая информация нажмите на ссылку для вызова функции.
-
В адресной строке браузера добавьте в ссылке параметр
api_key
, например?api_key=b95
. -
При успешном подключении в БД будет создана таблица
b95
и в нее будет добавлена одна запись. На странице появится сообщение в формате JSON, например:{ "info": "Создана таблица b95, вставлена одна запись" }
Как удалить созданные ресурсы
Чтобы перестать платить за созданные ресурсы: