tf_provider/TEST_STAND/CRUD/README.md

CRUD Test Stand

CRUD = Create / Read / Update / Delete — создать, прочитать, изменить, удалить.

Три приложения (Lucee, Flask, Node.js) работают с одной общей таблицей crud_items в PostgreSQL: в любом из них можно добавлять записи, просматривать их, редактировать и удалять.

Итог после запуска: добавьте запись в одном приложении — остальные два её увидят.

Манифесты: репозиторий примеров tf_examples, папка CRUD.

---

Быстрый старт

# 1. получить манифесты (нужен установленный Terraform — проверьте `terraform version`)
git clone https://gitea.services.ngcloud.ru/Nail/tf_examples.git
cd tf_examples/CRUD

# 2. заполнить переменные (что именно — в разделе «Что пользователь задаёт сам»)
cd pg     && cp terraform.tfvars.example terraform.tfvars  # api_token, realm, s3_name
cd ../apps && cp terraform.tfvars.example terraform.tfvars  # api_token, realm — те же

# 3. база данных (кластер создаётся несколько минут)
cd ../pg && terraform init && terraform apply

# 4. передать креды БД приложениям
terraform output -json > ../apps/creds.json

# 5. три приложения
cd ../apps && terraform init && terraform apply

После этого приложения открываются в браузере (имена заданы в apps/locals.tf):

Приложение	Адрес
Lucee	https://lucee-crud.luceek8s.dev.nubes.ru
Flask	https://flask-crud.pythonk8s.dev.nubes.ru
Node.js	https://nodejs-crud.nodejsk8s.dev.nubes.ru

Добавьте запись в одном приложении — она появится в двух других (таблица crud_items общая).

⚠️ В apps/creds.json пароль лежит открытым текстом: файл в apps/.gitignore — не коммитить и не пересылать.

Провайдер берётся из реестра: источник и версия заданы в pg/main.tf и apps/main.tf.

Подробности дальше: что задавать руками и как всё устроено.

---

Что создаётся

Ресурс	Имя (по умолчанию)	Что это
nubes_postgres	pg4crud2	кластер PostgreSQL 17
nubes_postgres_user	user4crudpg	пользователь БД, роль ddl_user
nubes_postgres_database	db4crudpg	база, владелец — этот пользователь
nubes_lucee	lucee-crud	приложение на Lucee 5.4
nubes_flask	flask-crud	приложение на Python 3.12
nubes_nodejs	nodejs-crud	приложение на Node.js 22

Все три приложения ходят в одну базу и одну таблицу — так видно, что CRUD работает одинаково с любого стека.

---

Как это устроено

Два каталога — два отдельных файла состояния Terraform:

CRUD/
├── pg/     база данных: кластер PostgreSQL + пользователь + база
└── apps/   приложения: Lucee + Flask + Node.js

• terraform apply и terraform destroy в apps/ меняют только приложения (создают, изменяют, удаляют) — база в pg/ не затрагивается;
• terraform apply и terraform destroy в pg/ меняют только базу — приложения в apps/ не затрагиваются;
• приложения можно пересоздавать сколько угодно, база при этом не меняется;
• связь между каталогами — файл apps/creds.json (шаг 4 быстрого старта): он делается из terraform output в pg/, поэтому после смены хоста или пароля его нужно обновить и повторить apply в apps/.

---

Что пользователь задаёт сам

Обязательные значения (без них apply не пройдёт)

Переменная	Где	Что это
api_token	pg/terraform.tfvars и apps/terraform.tfvars	токен Nubes: ЛК → Профиль → Токены → создать «Технический»
realm	там же, одно и то же значение	ресурсная платформа (кластер Kubernetes), например k8s-4-sandbox-nubes-ru; в apps/ обязан совпасть с pg/, иначе приложения не увидят кластер с базой
s3_name	pg/terraform.tfvars	имя (или UUID) экземпляра S3 для бэкапов: ЛК → S3

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

cd pg && cp terraform.tfvars.example terraform.tfvars
cd ../apps && cp terraform.tfvars.example terraform.tfvars

Имена: придумать самому, и они обязаны быть уникальными

Имя	Где задаётся	Правило
pg_resource_name (кластер)	pg/terraform.tfvars	уникально внутри сервиса postgres — другого инстанса с таким именем быть не должно
pg_username, pg_db_name	pg/terraform.tfvars	уникальны в пределах кластера; служебные имена (admin, postgres, standby) платформа не примет
lucee_resource_name, flask_resource_name, nodejs_resource_name	apps/locals.tf	уникальны внутри своего сервиса (lucee, flask, nodejs — у каждого свой набор имён)
lucee_domain, flask_domain, nodejs_domain	apps/locals.tf	здесь задаётся не полный домен, а имя — суффикс платформа добавляет сама: lucee-crud → lucee-crud.luceek8s.dev.nubes.ru, flask-crud → flask-crud.pythonk8s.dev.nubes.ru, nodejs-crud → nodejs-crud.nodejsk8s.dev.nubes.ru. Полные имена уникальны (это обычные DNS-имена), поэтому и задаваемое имя должно быть уникальным

Почему это важно: все ресурсы создаются с adopt_existing_on_create = true, а провайдер ищет инстанс по имени внутри своего сервиса. Если такое имя уже занято, он не станет создавать новый ресурс, а усыновит существующий — то есть при занятом имени можно подцепить чужой или старый инстанс. Если усыновление отключено, apply упадёт с «инстанс с resource_name … уже существует».

Можно не задавать (есть значения по умолчанию)

pg/main.tf: pg_cpu=500, pg_memory=512, pg_replicas=1, pg_disk=10, pg_version="17", pg_retain=14, pg_schedule="0 0 * * *", pg_timeout="11m", pg_username="user4crudpg", pg_role="ddl_user", pg_db_name="db4crudpg". Размеры приложений (*_cpu, *_memory, *_replicas) — в apps/locals.tf.

---

Код приложений (git)

Приложение	Репозиторий
Lucee (CFML)	https://gitea.services.ngcloud.ru/terraform/tfluceecrud.git
Flask (Python)	https://gitea.services.ngcloud.ru/terraform/tfflaskcrud.git
Node.js (Express)	https://gitea.services.ngcloud.ru/terraform/tfnodejscrud.git

Пути задаются в apps/locals.tf (lucee_git_path, flask_git_path, nodejs_git_path) — платформа сама клонирует код, собирать и заливать вручную не нужно.

Каждое приложение получает в json_env переменную SERVICE_NAME (lucee / flask / nodejs) — это значение колонки created_by, чтобы было видно, кто добавил строку.

---

Провайдер

Так он объявлен в pg/main.tf и apps/main.tf:

terraform {
  required_providers {
    nubes = {
      source  = "tf-registry.containerk8s.services.ngcloud.ru/nubes-test/nubes"
      version = "3.0.0"
    }
  }
}

provider "nubes" {
  api_token    = var.api_token
  api_endpoint = "https://lk-api-gateway-test.ngcloud.ru/api/v1/svc"
}

---

Повседневные операции

Задача	Команда
Передеплоить приложения	cd apps && terraform apply
Удалить приложения	cd apps && terraform destroy — БД не трогается
Изменить БД	cd pg && terraform apply
Удалить БД	cd pg && terraform destroy — кластер уйдёт в Suspend, а не удалится

При destroy БД кластер переводится в Suspend, а пользователь и база остаются (keep_on_destroy = true). Полное удаление: снять keep_on_destroy в pg/postgres_user_db.tf и apply.

---

Файлы

Файл	Что делает
pg/main.tf	провайдер, переменные кластера/пользователя/базы
pg/postgres.tf	кластер nubes_postgres.main_pg
pg/postgres_user_db.tf	пользователь crud_user_0 + база pg_db
pg/outputs.tf	хост, порт, юзер, база, пароль — для выгрузки кредов
apps/main.tf	провайдер, переменные приложений
apps/locals.tf	чтение creds.json, домены, версии, размеры
apps/lucee.tf, apps/flask.tf, apps/nodejs.tf	три приложения
pg/terraform.tfvars.example, apps/terraform.tfvars.example	шаблоны для копирования в terraform.tfvars
apps/creds.json	создаётся шагом 4 быстрого старта, не в git

---

Особенности этого примера

• adopt_existing_on_create = true у всех ресурсов — если инстанс с таким именем уже есть (например после destroy, который приостанавливает, а не удаляет), провайдер его усыновит, а не упадёт с «ресурс с таким именем уже существует».
• keep_on_destroy = true у пользователя и базы: при destroy в pg/ кластер уходит в Suspend, а пользователь и база остаются. Иначе база исчезла бы вместе с кластером. Повторный apply возвращает их в state (усыновление).
• Домены приложений должны быть уникальными — lucee_domain, flask_domain, nodejs_domain в apps/locals.tf. Иначе платформа откажет.
• postgres_conf — ключи строго как в спецификации платформы: paramName / paramValue (camelCase). Допустимы только log_connections и log_disconnections.
• realm — рабочая ресурсная платформа. Если у неё нет ёмкости, операция падает с сообщением «Невозможно развернуть приложение в данной ресурсной платформе».

---

Справка: выходные параметры pg/

В pg/outputs.tf объявлено шесть выходов:

Выход	Значение	Откуда
pg_host	внутренний хост master — приложения ходят к базе по внутренней сети кластера, а сами приложения открываются по внешним доменам (см. «Быстрый старт»)	state_out_flat["internalMaster"] кластера
pg_port	5432	константа в outputs.tf
pg_username	имя пользователя БД	выход подресурса nubes_postgres_user
pg_db_name	имя базы	выход nubes_postgres_database
pg_password	пароль, sensitive = true	выход подресурса nubes_postgres_user: платформа генерирует пароль сама при создании пользователя, провайдер читает его из Vault и отдаёт выходом подресурса
pg_ssl_mode	require	константа в outputs.tf

terraform output -json кладёт в файл не голые значения, а объекты вида { "sensitive": ..., "type": ..., "value": ... }:

{
  "pg_host":     { "sensitive": false, "type": "string", "value": "<хост master>" },
  "pg_password": { "sensitive": true,  "type": "string", "value": "<пароль>" }
}

Поэтому в apps/locals.tf значение берётся через .value:

creds   = jsondecode(file("${path.module}/creds.json"))
pg_host = local.creds.pg_host.value
pg_pass = local.creds.pg_password.value

Дальше apps/*.tf передают эти значения приложениям как переменные окружения:

Выход pg/	Flask	Node.js	Lucee
pg_host	PGHOST	PGHOST	PGHOST
pg_port	PGPORT	PGPORT	PGPORT
pg_username	PGUSER	PGUSER	PGUSER
pg_password	PGPASSWORD	PGPASSWORD	PGPASSWORD
pg_db_name	PGDATABASE	PGDATABASE	— (входит в строки подключения ниже)
pg_ssl_mode	PGSSLMODE	PGSSLMODE	PGSSLMODE

Кроме этого Lucee получает testds_connectionString и DATABASE_URL — это строки подключения, собранные из хоста, порта, пользователя, пароля и имени базы (apps/lucee.tf), а не отдельные значения выходов. Остальные testds_* (class, bundleName, bundleVersion, username, password, connectionLimit, liveTimeout, validate) — параметры JDBC-драйвера.