docs(crud): README и страница сведены в один документ + исправлен бред по коду

Разбор замечаний ревью (проверено по манифестам):
1) рассинхрон: теперь одинаковый набор и порядок разделов в обоих файлах
   (Быстрый старт, Что создаётся, Как это устроено, Что пользователь задаёт сам,
   Код приложений (git), Провайдер, Повседневные операции, Файлы, Особенности
   этого примера, Справка). На странице переименован раздел, перенесены Код
   приложений и Особенности, добавлены Повседневные операции и Файлы; в README
   добавлены Что создаётся, Провайдер и Особенности;
2) ошибка в таблице env: pg_db_name -> Lucee показывал testds_connectionString и
   DATABASE_URL как отдельные значения. По apps/lucee.tf это составные строки
   подключения, а PGDATABASE у Lucee нет; таблица исправлена + пояснение про
   testds_* (JDBC-параметры);
3) pg_host: пояснено, что это внутренний хост для приложений, а сами приложения
   открываются по внешним доменам;
4) пути репозиториев в таблицах приведены к виду из apps/locals.tf — с .git;
5) «уникально в пределах стенда» -> «внутри своего сервиса»;
6) postgres_conf и прочие особенности теперь и в README.
Проверено: пофайловое сравнение разделов (различия только в --- и
{{плейсхолдерах}}), живая страница 166060 байт, cmp с локальной сборкой совпал.
This commit is contained in:
Repinoid
2026-10-02 08:58:38 +03:00
parent 39af8bfcbf
commit 17350eed89
2 changed files with 146 additions and 54 deletions
+76 -14
View File
@@ -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-драйвера.