From 17350eed898bc999bbe45ba1c6409388d92a7930 Mon Sep 17 00:00:00 2001 From: Repinoid Date: Fri, 2 Oct 2026 08:58:38 +0300 Subject: [PATCH] =?UTF-8?q?docs(crud):=20README=20=D0=B8=20=D1=81=D1=82?= =?UTF-8?q?=D1=80=D0=B0=D0=BD=D0=B8=D1=86=D0=B0=20=D1=81=D0=B2=D0=B5=D0=B4?= =?UTF-8?q?=D0=B5=D0=BD=D1=8B=20=D0=B2=20=D0=BE=D0=B4=D0=B8=D0=BD=20=D0=B4?= =?UTF-8?q?=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82=20+=20=D0=B8=D1=81?= =?UTF-8?q?=D0=BF=D1=80=D0=B0=D0=B2=D0=BB=D0=B5=D0=BD=20=D0=B1=D1=80=D0=B5?= =?UTF-8?q?=D0=B4=20=D0=BF=D0=BE=20=D0=BA=D0=BE=D0=B4=D1=83=20=D0=A0=D0=B0?= =?UTF-8?q?=D0=B7=D0=B1=D0=BE=D1=80=20=D0=B7=D0=B0=D0=BC=D0=B5=D1=87=D0=B0?= =?UTF-8?q?=D0=BD=D0=B8=D0=B9=20=D1=80=D0=B5=D0=B2=D1=8C=D1=8E=20(=D0=BF?= =?UTF-8?q?=D1=80=D0=BE=D0=B2=D0=B5=D1=80=D0=B5=D0=BD=D0=BE=20=D0=BF=D0=BE?= =?UTF-8?q?=20=D0=BC=D0=B0=D0=BD=D0=B8=D1=84=D0=B5=D1=81=D1=82=D0=B0=D0=BC?= =?UTF-8?q?):=201)=20=D1=80=D0=B0=D1=81=D1=81=D0=B8=D0=BD=D1=85=D1=80?= =?UTF-8?q?=D0=BE=D0=BD:=20=D1=82=D0=B5=D0=BF=D0=B5=D1=80=D1=8C=20=D0=BE?= =?UTF-8?q?=D0=B4=D0=B8=D0=BD=D0=B0=D0=BA=D0=BE=D0=B2=D1=8B=D0=B9=20=D0=BD?= =?UTF-8?q?=D0=B0=D0=B1=D0=BE=D1=80=20=D0=B8=20=D0=BF=D0=BE=D1=80=D1=8F?= =?UTF-8?q?=D0=B4=D0=BE=D0=BA=20=D1=80=D0=B0=D0=B7=D0=B4=D0=B5=D0=BB=D0=BE?= =?UTF-8?q?=D0=B2=20=D0=B2=20=D0=BE=D0=B1=D0=BE=D0=B8=D1=85=20=D1=84=D0=B0?= =?UTF-8?q?=D0=B9=D0=BB=D0=B0=D1=85=20=20=20=20(=D0=91=D1=8B=D1=81=D1=82?= =?UTF-8?q?=D1=80=D1=8B=D0=B9=20=D1=81=D1=82=D0=B0=D1=80=D1=82,=20=D0=A7?= =?UTF-8?q?=D1=82=D0=BE=20=D1=81=D0=BE=D0=B7=D0=B4=D0=B0=D1=91=D1=82=D1=81?= =?UTF-8?q?=D1=8F,=20=D0=9A=D0=B0=D0=BA=20=D1=8D=D1=82=D0=BE=20=D1=83?= =?UTF-8?q?=D1=81=D1=82=D1=80=D0=BE=D0=B5=D0=BD=D0=BE,=20=D0=A7=D1=82?= =?UTF-8?q?=D0=BE=20=D0=BF=D0=BE=D0=BB=D1=8C=D0=B7=D0=BE=D0=B2=D0=B0=D1=82?= =?UTF-8?q?=D0=B5=D0=BB=D1=8C=20=D0=B7=D0=B0=D0=B4=D0=B0=D1=91=D1=82=20?= =?UTF-8?q?=D1=81=D0=B0=D0=BC,=20=20=20=20=D0=9A=D0=BE=D0=B4=20=D0=BF?= =?UTF-8?q?=D1=80=D0=B8=D0=BB=D0=BE=D0=B6=D0=B5=D0=BD=D0=B8=D0=B9=20(git),?= =?UTF-8?q?=20=D0=9F=D1=80=D0=BE=D0=B2=D0=B0=D0=B9=D0=B4=D0=B5=D1=80,=20?= =?UTF-8?q?=D0=9F=D0=BE=D0=B2=D1=81=D0=B5=D0=B4=D0=BD=D0=B5=D0=B2=D0=BD?= =?UTF-8?q?=D1=8B=D0=B5=20=D0=BE=D0=BF=D0=B5=D1=80=D0=B0=D1=86=D0=B8=D0=B8?= =?UTF-8?q?,=20=D0=A4=D0=B0=D0=B9=D0=BB=D1=8B,=20=D0=9E=D1=81=D0=BE=D0=B1?= =?UTF-8?q?=D0=B5=D0=BD=D0=BD=D0=BE=D1=81=D1=82=D0=B8=20=20=20=20=D1=8D?= =?UTF-8?q?=D1=82=D0=BE=D0=B3=D0=BE=20=D0=BF=D1=80=D0=B8=D0=BC=D0=B5=D1=80?= =?UTF-8?q?=D0=B0,=20=D0=A1=D0=BF=D1=80=D0=B0=D0=B2=D0=BA=D0=B0).=20=D0=9D?= =?UTF-8?q?=D0=B0=20=D1=81=D1=82=D1=80=D0=B0=D0=BD=D0=B8=D1=86=D0=B5=20?= =?UTF-8?q?=D0=BF=D0=B5=D1=80=D0=B5=D0=B8=D0=BC=D0=B5=D0=BD=D0=BE=D0=B2?= =?UTF-8?q?=D0=B0=D0=BD=20=D1=80=D0=B0=D0=B7=D0=B4=D0=B5=D0=BB,=20=D0=BF?= =?UTF-8?q?=D0=B5=D1=80=D0=B5=D0=BD=D0=B5=D1=81=D0=B5=D0=BD=D1=8B=20=D0=9A?= =?UTF-8?q?=D0=BE=D0=B4=20=20=20=20=D0=BF=D1=80=D0=B8=D0=BB=D0=BE=D0=B6?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D0=B9=20=D0=B8=20=D0=9E=D1=81=D0=BE=D0=B1?= =?UTF-8?q?=D0=B5=D0=BD=D0=BD=D0=BE=D1=81=D1=82=D0=B8,=20=D0=B4=D0=BE?= =?UTF-8?q?=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5=D0=BD=D1=8B=20=D0=9F=D0=BE=D0=B2?= =?UTF-8?q?=D1=81=D0=B5=D0=B4=D0=BD=D0=B5=D0=B2=D0=BD=D1=8B=D0=B5=20=D0=BE?= =?UTF-8?q?=D0=BF=D0=B5=D1=80=D0=B0=D1=86=D0=B8=D0=B8=20=D0=B8=20=D0=A4?= =?UTF-8?q?=D0=B0=D0=B9=D0=BB=D1=8B;=20=D0=B2=20README=20=20=20=20=D0=B4?= =?UTF-8?q?=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5=D0=BD=D1=8B=20=D0=A7=D1=82?= =?UTF-8?q?=D0=BE=20=D1=81=D0=BE=D0=B7=D0=B4=D0=B0=D1=91=D1=82=D1=81=D1=8F?= =?UTF-8?q?,=20=D0=9F=D1=80=D0=BE=D0=B2=D0=B0=D0=B9=D0=B4=D0=B5=D1=80=20?= =?UTF-8?q?=D0=B8=20=D0=9E=D1=81=D0=BE=D0=B1=D0=B5=D0=BD=D0=BD=D0=BE=D1=81?= =?UTF-8?q?=D1=82=D0=B8;=202)=20=D0=BE=D1=88=D0=B8=D0=B1=D0=BA=D0=B0=20?= =?UTF-8?q?=D0=B2=20=D1=82=D0=B0=D0=B1=D0=BB=D0=B8=D1=86=D0=B5=20env:=20pg?= =?UTF-8?q?=5Fdb=5Fname=20->=20Lucee=20=D0=BF=D0=BE=D0=BA=D0=B0=D0=B7?= =?UTF-8?q?=D1=8B=D0=B2=D0=B0=D0=BB=20testds=5FconnectionString=20=D0=B8?= =?UTF-8?q?=20=20=20=20DATABASE=5FURL=20=D0=BA=D0=B0=D0=BA=20=D0=BE=D1=82?= =?UTF-8?q?=D0=B4=D0=B5=D0=BB=D1=8C=D0=BD=D1=8B=D0=B5=20=D0=B7=D0=BD=D0=B0?= =?UTF-8?q?=D1=87=D0=B5=D0=BD=D0=B8=D1=8F.=20=D0=9F=D0=BE=20apps/lucee.tf?= =?UTF-8?q?=20=D1=8D=D1=82=D0=BE=20=D1=81=D0=BE=D1=81=D1=82=D0=B0=D0=B2?= =?UTF-8?q?=D0=BD=D1=8B=D0=B5=20=D1=81=D1=82=D1=80=D0=BE=D0=BA=D0=B8=20=20?= =?UTF-8?q?=20=20=D0=BF=D0=BE=D0=B4=D0=BA=D0=BB=D1=8E=D1=87=D0=B5=D0=BD?= =?UTF-8?q?=D0=B8=D1=8F,=20=D0=B0=20PGDATABASE=20=D1=83=20Lucee=20=D0=BD?= =?UTF-8?q?=D0=B5=D1=82;=20=D1=82=D0=B0=D0=B1=D0=BB=D0=B8=D1=86=D0=B0=20?= =?UTF-8?q?=D0=B8=D1=81=D0=BF=D1=80=D0=B0=D0=B2=D0=BB=D0=B5=D0=BD=D0=B0=20?= =?UTF-8?q?+=20=D0=BF=D0=BE=D1=8F=D1=81=D0=BD=D0=B5=D0=BD=D0=B8=D0=B5=20?= =?UTF-8?q?=D0=BF=D1=80=D0=BE=20=20=20=20testds=5F*=20(JDBC-=D0=BF=D0=B0?= =?UTF-8?q?=D1=80=D0=B0=D0=BC=D0=B5=D1=82=D1=80=D1=8B);=203)=20pg=5Fhost:?= =?UTF-8?q?=20=D0=BF=D0=BE=D1=8F=D1=81=D0=BD=D0=B5=D0=BD=D0=BE,=20=D1=87?= =?UTF-8?q?=D1=82=D0=BE=20=D1=8D=D1=82=D0=BE=20=D0=B2=D0=BD=D1=83=D1=82?= =?UTF-8?q?=D1=80=D0=B5=D0=BD=D0=BD=D0=B8=D0=B9=20=D1=85=D0=BE=D1=81=D1=82?= =?UTF-8?q?=20=D0=B4=D0=BB=D1=8F=20=D0=BF=D1=80=D0=B8=D0=BB=D0=BE=D0=B6?= =?UTF-8?q?=D0=B5=D0=BD=D0=B8=D0=B9,=20=D0=B0=20=D1=81=D0=B0=D0=BC=D0=B8?= =?UTF-8?q?=20=D0=BF=D1=80=D0=B8=D0=BB=D0=BE=D0=B6=D0=B5=D0=BD=D0=B8=D1=8F?= =?UTF-8?q?=20=20=20=20=D0=BE=D1=82=D0=BA=D1=80=D1=8B=D0=B2=D0=B0=D1=8E?= =?UTF-8?q?=D1=82=D1=81=D1=8F=20=D0=BF=D0=BE=20=D0=B2=D0=BD=D0=B5=D1=88?= =?UTF-8?q?=D0=BD=D0=B8=D0=BC=20=D0=B4=D0=BE=D0=BC=D0=B5=D0=BD=D0=B0=D0=BC?= =?UTF-8?q?;=204)=20=D0=BF=D1=83=D1=82=D0=B8=20=D1=80=D0=B5=D0=BF=D0=BE?= =?UTF-8?q?=D0=B7=D0=B8=D1=82=D0=BE=D1=80=D0=B8=D0=B5=D0=B2=20=D0=B2=20?= =?UTF-8?q?=D1=82=D0=B0=D0=B1=D0=BB=D0=B8=D1=86=D0=B0=D1=85=20=D0=BF=D1=80?= =?UTF-8?q?=D0=B8=D0=B2=D0=B5=D0=B4=D0=B5=D0=BD=D1=8B=20=D0=BA=20=D0=B2?= =?UTF-8?q?=D0=B8=D0=B4=D1=83=20=D0=B8=D0=B7=20apps/locals.tf=20=E2=80=94?= =?UTF-8?q?=20=D1=81=20.git;=205)=20=C2=AB=D1=83=D0=BD=D0=B8=D0=BA=D0=B0?= =?UTF-8?q?=D0=BB=D1=8C=D0=BD=D0=BE=20=D0=B2=20=D0=BF=D1=80=D0=B5=D0=B4?= =?UTF-8?q?=D0=B5=D0=BB=D0=B0=D1=85=20=D1=81=D1=82=D0=B5=D0=BD=D0=B4=D0=B0?= =?UTF-8?q?=C2=BB=20->=20=C2=AB=D0=B2=D0=BD=D1=83=D1=82=D1=80=D0=B8=20?= =?UTF-8?q?=D1=81=D0=B2=D0=BE=D0=B5=D0=B3=D0=BE=20=D1=81=D0=B5=D1=80=D0=B2?= =?UTF-8?q?=D0=B8=D1=81=D0=B0=C2=BB;=206)=20postgres=5Fconf=20=D0=B8=20?= =?UTF-8?q?=D0=BF=D1=80=D0=BE=D1=87=D0=B8=D0=B5=20=D0=BE=D1=81=D0=BE=D0=B1?= =?UTF-8?q?=D0=B5=D0=BD=D0=BD=D0=BE=D1=81=D1=82=D0=B8=20=D1=82=D0=B5=D0=BF?= =?UTF-8?q?=D0=B5=D1=80=D1=8C=20=D0=B8=20=D0=B2=20README.=20=D0=9F=D1=80?= =?UTF-8?q?=D0=BE=D0=B2=D0=B5=D1=80=D0=B5=D0=BD=D0=BE:=20=D0=BF=D0=BE?= =?UTF-8?q?=D1=84=D0=B0=D0=B9=D0=BB=D0=BE=D0=B2=D0=BE=D0=B5=20=D1=81=D1=80?= =?UTF-8?q?=D0=B0=D0=B2=D0=BD=D0=B5=D0=BD=D0=B8=D0=B5=20=D1=80=D0=B0=D0=B7?= =?UTF-8?q?=D0=B4=D0=B5=D0=BB=D0=BE=D0=B2=20(=D1=80=D0=B0=D0=B7=D0=BB?= =?UTF-8?q?=D0=B8=D1=87=D0=B8=D1=8F=20=D1=82=D0=BE=D0=BB=D1=8C=D0=BA=D0=BE?= =?UTF-8?q?=20=D0=B2=20---=20=D0=B8=20{{=D0=BF=D0=BB=D0=B5=D0=B9=D1=81?= =?UTF-8?q?=D1=85=D0=BE=D0=BB=D0=B4=D0=B5=D1=80=D0=B0=D1=85}}),=20=D0=B6?= =?UTF-8?q?=D0=B8=D0=B2=D0=B0=D1=8F=20=D1=81=D1=82=D1=80=D0=B0=D0=BD=D0=B8?= =?UTF-8?q?=D1=86=D0=B0=20166060=20=D0=B1=D0=B0=D0=B9=D1=82,=20cmp=20?= =?UTF-8?q?=D1=81=20=D0=BB=D0=BE=D0=BA=D0=B0=D0=BB=D1=8C=D0=BD=D0=BE=D0=B9?= =?UTF-8?q?=20=D1=81=D0=B1=D0=BE=D1=80=D0=BA=D0=BE=D0=B9=20=D1=81=D0=BE?= =?UTF-8?q?=D0=B2=D0=BF=D0=B0=D0=BB.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- TEST_STAND/CRUD/README.md | 90 ++++++++++++++++++++++---- docs/curated/crud/three_apps.md | 110 ++++++++++++++++++++------------ 2 files changed, 146 insertions(+), 54 deletions(-) diff --git a/TEST_STAND/CRUD/README.md b/TEST_STAND/CRUD/README.md index ffee352..e152927 100644 --- a/TEST_STAND/CRUD/README.md +++ b/TEST_STAND/CRUD/README.md @@ -48,6 +48,22 @@ cd ../apps && terraform init && terraform apply --- +## Что создаётся + +| Ресурс | Имя (по умолчанию) | Что это | +|---|---|---| +| `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: @@ -86,9 +102,9 @@ cd ../apps && cp terraform.tfvars.example terraform.tfvars | Имя | Где задаётся | Правило | |---|---|---| -| `pg_resource_name` (кластер) | `pg/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_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`, а провайдер ищет @@ -108,15 +124,39 @@ cd ../apps && cp terraform.tfvars.example terraform.tfvars ## Код приложений (git) -Платформа сама клонирует код из репозиториев — собирать и заливать вручную не нужно: - | Приложение | Репозиторий | |---|---| -| Lucee (CFML) | [`terraform/tfluceecrud`](https://gitea.services.ngcloud.ru/terraform/tfluceecrud) | -| Flask (Python) | [`terraform/tfflaskcrud`](https://gitea.services.ngcloud.ru/terraform/tfflaskcrud) | -| Node.js (Express) | [`terraform/tfnodejscrud`](https://gitea.services.ngcloud.ru/terraform/tfnodejscrud) | +| 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`. +Пути задаются в `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`: + +```hcl +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" +} +``` --- @@ -150,13 +190,30 @@ cd ../apps && cp terraform.tfvars.example terraform.tfvars --- +## Особенности этого примера + +- **`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_host` | внутренний хост master — приложения ходят к базе по внутренней сети кластера, а сами приложения открываются по внешним доменам (см. «Быстрый старт») | `state_out_flat["internalMaster"]` кластера | | `pg_port` | `5432` | константа в `outputs.tf` | | `pg_username` | имя пользователя БД | выход подресурса `nubes_postgres_user` | | `pg_db_name` | имя базы | выход `nubes_postgres_database` | @@ -184,9 +241,14 @@ pg_pass = local.creds.pg_password.value | Выход `pg/` | Flask | Node.js | Lucee | |---|---|---|---| -| `pg_host` | `PGHOST` | `PGHOST` | `PGHOST`, `testds_connectionString` | -| `pg_port` | `PGPORT` | `PGPORT` | `PGPORT`, `testds_connectionString` | -| `pg_username` | `PGUSER` | `PGUSER` | `PGUSER`, `testds_username` | -| `pg_password` | `PGPASSWORD` | `PGPASSWORD` | `PGPASSWORD`, `testds_password` | -| `pg_db_name` | `PGDATABASE` | `PGDATABASE` | `testds_connectionString`, `DATABASE_URL` | +| `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-драйвера. diff --git a/docs/curated/crud/three_apps.md b/docs/curated/crud/three_apps.md index c229122..d9dd6cc 100644 --- a/docs/curated/crud/three_apps.md +++ b/docs/curated/crud/three_apps.md @@ -58,22 +58,7 @@ cd ../apps && terraform init && terraform apply Все три приложения ходят в одну базу и одну таблицу — так видно, что CRUD работает одинаково с любого стека. -## Код приложений (git) - -| Приложение | Репозиторий | -|---|---| -| Lucee (CFML) | `https://gitea.services.ngcloud.ru/terraform/tfluceecrud` | -| Flask (Python) | `https://gitea.services.ngcloud.ru/terraform/tfflaskcrud` | -| Node.js (Express) | `https://gitea.services.ngcloud.ru/terraform/tfnodejscrud` | - -Пути к репозиториям задаются в `apps/locals.tf` (`lucee_git_path`, -`flask_git_path`, `nodejs_git_path`). Платформа сама клонирует код — собирать и заливать -вручную не нужно. - -Каждое приложение получает в `json_env` переменную `SERVICE_NAME` (`lucee` / `flask` / `nodejs`) — -это значение колонки `created_by`, чтобы было видно, кто добавил строку. - -## Структура манифестов +## Как это устроено Два каталога — два отдельных файла состояния Terraform: @@ -83,11 +68,10 @@ CRUD/ └── apps/ приложения: Lucee + Flask + Node.js ``` -- `terraform apply` и `terraform destroy` в `apps/` меняют **только приложения** — база в `pg/` не затрагивается; +- `terraform apply` и `terraform destroy` в `apps/` меняют **только приложения** (создают, изменяют, удаляют) — база в `pg/` не затрагивается; - `terraform apply` и `terraform destroy` в `pg/` меняют только базу — приложения в `apps/` не затрагиваются; - приложения можно пересоздавать сколько угодно, база при этом не меняется; -- связь между каталогами — файл `apps/creds.json`: он делается из `terraform output` в `pg/`, - поэтому после смены хоста или пароля его нужно обновить и повторить `apply` в `apps/`. +- связь между каталогами — файл `apps/creds.json` (шаг 4 быстрого старта): он делается из `terraform output` в `pg/`, поэтому после смены хоста или пароля его нужно обновить и повторить `apply` в `apps/`. ## Что пользователь задаёт сам @@ -110,9 +94,9 @@ cd ../apps && cp terraform.tfvars.example terraform.tfvars | Имя | Где задаётся | Правило | |---|---|---| -| `pg_resource_name` (кластер) | `pg/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_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`, а провайдер ищет @@ -128,6 +112,20 @@ cd ../apps && cp terraform.tfvars.example terraform.tfvars `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`, чтобы было видно, кто добавил строку. + ## Провайдер ```hcl @@ -146,13 +144,54 @@ provider "nubes" { } ``` +## Повседневные операции + +| Задача | Команда | +|---|---| +| Передеплоить приложения | `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_host` | внутренний хост master — приложения ходят к базе по внутренней сети кластера, а сами приложения открываются по внешним доменам (см. «Быстрый старт») | `state_out_flat["internalMaster"]` кластера | | `pg_port` | `5432` | константа в `outputs.tf` | | `pg_username` | имя пользователя БД | выход подресурса `nubes_postgres_user` | | `pg_db_name` | имя базы | выход `nubes_postgres_database` | @@ -181,24 +220,15 @@ pg_pass = local.creds.pg_password.value | Выход `pg/` | Flask | Node.js | Lucee | |---|---|---|---| -| `pg_host` | `PGHOST` | `PGHOST` | `PGHOST`, `testds_connectionString` | -| `pg_port` | `PGPORT` | `PGPORT` | `PGPORT`, `testds_connectionString` | -| `pg_username` | `PGUSER` | `PGUSER` | `PGUSER`, `testds_username` | -| `pg_password` | `PGPASSWORD` | `PGPASSWORD` | `PGPASSWORD`, `testds_password` | -| `pg_db_name` | `PGDATABASE` | `PGDATABASE` | `testds_connectionString`, `DATABASE_URL` | +| `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-драйвера. -- **`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`** — рабочая ресурсная платформа. Если у неё нет ёмкости, операция падает - с сообщением «Невозможно развернуть приложение в данной ресурсной платформе».