terraform/tf_provider
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(crud): сначала действия, потом описание; убрано недоступное пользователю

Browse Source 
Требования владельца: «СНАЧАЛА — кратко чё это вообще и ДЕЙСТВИЯ … всё остальное
описание — ПОСЛЕ»; «юзер НЕ МОЖЕТ вводить никакие команды … УБЕРИ ЭТО и подобное».
- раздел «Быстрый старт» — первым: клонирование, заполнение переменных, apply pg,
  creds.json, apply apps, адреса приложений, предупреждение про пароль в файле;
  подробное описание — ниже (READМE: Как это устроено / Что задаёт пользователь /
  Код приложений / Повседневные операции / Файлы / Справка);
- из README убран раздел «Если apply упал», со страницы — «Диагностика, если
  apply упал»: пользователь не может делать вызовы вида
  GET {api_endpoint}/instanceOperations/... — вместо инструкции было ничего не
  работающее; вместе с разделом убрана ссылка на HISTORY/60_stands/... (внутренний
  репозиторий);
- убраны ссылки на внутренний код (provider/internal/.../crud.go:171,
  refsvc_find.go:47) и на строки apps/locals.tf:45,57,68; убран абзац про прежние
  имена tflucee/tfflask/tfnodejs (внутренняя история);
- со страницы убрано «смотрите журнал операции» в разделе «Особенности».
Проверено на живой странице (162257 байт, совпадает с локальной сборкой):
instanceOperations / errorLog / HISTORY/ / crud.go / refsvc_find — 0 вхождений;
первый раздел — «Быстрый старт».
This commit is contained in:
Repinoid
2026-10-02 08:46:46 +03:00
parent 02114bf195
commit bfa9d5f626
2 changed files with 72 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TEST_STAND/CRUD/README.md
+37 -97
View File
@@ -9,24 +9,50 @@ CRUD = Create / Read / Update / Delete — создать, прочитать,
---
## Где взять манифесты
Каталог примера — `TEST_STAND/CRUD` в репозитории провайдера. Клонируйте и перейдите в него:
## Быстрый старт
```bash
# 1. получить манифесты (нужен установленный Terraform — проверьте `terraform version`)
git clone https://gitea.services.ngcloud.ru/terraform/tf_provider.git
cd tf_provider/TEST_STAND/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
```
Нужен установленный Terraform:
После этого приложения открываются в браузере (имена заданы в `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> |
Свои адреса — из state:
```bash
terraform version
grep -o 'https://[a-z0-9.-]*\.dev\.nubes\.ru' apps/terraform.tfstate | sort -u
```
Провайдер берётся из реестра — источник и версия заданы в `pg/main.tf` и `apps/main.tf`
(test-стенд: `tf-registry.containerk8s.services.ngcloud.ru/nubes-test/nubes`, версия `3.0.0`).
Дальше все команды выполняются из каталога `TEST_STAND/CRUD`.
Добавьте запись в одном приложении — она появится в двух других (таблица `crud_items` общая).
> ⚠️ В `apps/creds.json` пароль лежит **открытым текстом**: файл в `apps/.gitignore` — не коммитить и не пересылать.
Провайдер берётся из реестра: источник и версия заданы в `pg/main.tf` и `apps/main.tf`
(test-стенд — `tf-registry.containerk8s.services.ngcloud.ru/nubes-test/nubes`, версия `3.0.0`).
Все команды выполняются из каталога `TEST_STAND/CRUD`.
Подробности дальше: что задавать руками, как всё устроено, что делать при ошибке.
---
@@ -43,7 +69,7 @@ CRUD/
- `terraform apply` и `terraform destroy` в `apps/` меняют **только приложения** (создают, изменяют, удаляют) — база в `pg/` не затрагивается;
- `terraform apply` и `terraform destroy` в `pg/` меняют только базу — приложения в `apps/` не затрагиваются;
- приложения можно пересоздавать сколько угодно, база при этом не меняется;
- связь между каталогами — файл `apps/creds.json` (см. шаг 2): он делается из `terraform output` в `pg/`, поэтому после смены хоста или пароля его нужно обновить и повторить `apply` в `apps/`.
- связь между каталогами — файл `apps/creds.json` (шаг 4 быстрого старта): он делается из `terraform output` в `pg/`, поэтому после смены хоста или пароля его нужно обновить и повторить `apply` в `apps/`.
---
@@ -74,15 +100,11 @@ cd ../apps && cp terraform.tfvars.example terraform.tfvars
| `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`, а провайдер ищет
инстанс **по имени внутри своего сервиса** (`provider/internal/resources_core/crud.go:171`,
`provider/internal/core/refsvc_find.go:47`). Если такое имя уже занято, он не станет создавать
инстанс **по имени внутри своего сервиса**. Если такое имя уже занято, он не станет создавать
новый ресурс, а **усыновит** существующий — то есть при занятом имени можно подцепить чужой или
старый инстанс. Если усыновление отключено, `apply` упадёт с «инстанс с resource_name … уже
существует».
Живой пример: прежние имена `tflucee`, `tfflask`, `tfnodejs` заняты старыми инстансами,
поэтому в стенде взяты `lucee-crud`, `flask-crud`, `nodejs-crud` (`apps/locals.tf:45,57,68`).
### Можно не задавать (есть значения по умолчанию)
`pg/main.tf`: `pg_cpu=500`, `pg_memory=512`, `pg_replicas=1`, `pg_disk=10`, `pg_version="17"`,
@@ -106,73 +128,6 @@ cd ../apps && cp terraform.tfvars.example terraform.tfvars
---
## Запуск — четыре шага
### 1. База данных (`pg/`)
```bash
cd pg
cp terraform.tfvars.example terraform.tfvars
# заполнить api_token, realm, s3_name (раздел «Что пользователь задаёт сам»)
terraform init
terraform apply
```
Создадутся кластер (несколько минут), пользователь БД и база.
Обязательные значения — `api_token`, `realm`, `s3_name`. Полный список и правила по именам —
в разделе «Что пользователь задаёт сам» выше.
### 2. Передать креды БД в `apps/`
```bash
# всё ещё в папке pg/
terraform output -json > ../apps/creds.json
```
Одна команда выгружает хост, порт, имя пользователя, имя БД и пароль в `apps/creds.json`.
Приложения читают этот файл (см. `apps/locals.tf`).
> ⚠️ В `creds.json` пароль лежит **открытым текстом**: файл в `apps/.gitignore`, не коммитить и не пересылать.
Что именно выгружается и как это читают приложения — в разделе «Справка» в конце файла.
### 3. Приложения (`apps/`)
```bash
cd ../apps
cp terraform.tfvars.example terraform.tfvars
# заполнить api_token и realm — те же, что в pg/
terraform init
terraform apply
```
Создадутся три приложения, подключённые к общей БД.
Обязательные значения — `api_token` и `realm` (те же, что в `pg/`). Имена доменов и имена
ресурсов приложений задаются в `apps/locals.tf` — см. раздел «Что пользователь задаёт сам».
### 4. Проверить
Откройте в браузере три адреса (это полные домены, которые платформа построила из имён в
`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> |
Свои адреса можно посмотреть в state:
```bash
grep -o 'https://[a-z0-9.-]*\.dev\.nubes\.ru' apps/terraform.tfstate | sort -u
```
Добавьте запись в одном приложении — она появится в двух других (таблица `crud_items` общая).
---
## Повседневные операции
| Задача | Команда |
@@ -187,21 +142,6 @@ grep -o 'https://[a-z0-9.-]*\.dev\.nubes\.ru' apps/terraform.tfstate | sort -u
---
## Если `apply` упал
Текст ошибки в поле `errorLog` у платформы **не всегда отражает суть** — реальная причина видна
в журнале операции:
```bash
GET {api_endpoint}/instanceOperations/<UID>?fields=cfsParams,errorLog,stages
```
`stages[].stageMsg` — массив пар `[заголовок, лог]`, смотреть последнюю запись; `cfsParams` —
фактический набор параметров, ушедший на платформу. Разбор реального случая:
`HISTORY/60_stands/2026-10-01_test_crud_pg_create_failure.md`.
---
## Файлы
| Файл | Что делает |
@@ -214,7 +154,7 @@ GET {api_endpoint}/instanceOperations/<UID>?fields=cfsParams,errorLog,stages
| `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` | генерируется шагом 2, **не в git** |
| `apps/creds.json` | создаётся шагом 4 быстрого старта, **не в git** |
---
docs/curated/crud/three_apps.md
+35 -89
View File
@@ -7,23 +7,49 @@
Манифесты: `TEST_STAND/CRUD/` в репозитории провайдера — два каталога: `pg/` (база) и `apps/` (приложения).
`DEV_STAND/CRUD/` — тот же пример, но по старой схеме: всё в одной папке.
## Где взять манифесты
Клонируйте репозиторий провайдера и перейдите в каталог примера:
## Быстрый старт
```bash
# 1. получить манифесты (нужен установленный Terraform — проверьте `terraform version`)
git clone https://gitea.services.ngcloud.ru/terraform/tf_provider.git
cd tf_provider/TEST_STAND/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
```
Нужен установленный Terraform:
После этого приложения открываются в браузере (имена заданы в `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> |
Свои адреса — из state:
```bash
terraform version
grep -o 'https://[a-z0-9.-]*\.dev\.nubes\.ru' apps/terraform.tfstate | sort -u
```
Провайдер берётся из реестра — источник и версия заданы в `pg/main.tf` и `apps/main.tf`.
Дальше все команды выполняются из каталога `TEST_STAND/CRUD`.
Добавьте запись в одном приложении — она появится в двух других (таблица `crud_items` общая).
> ⚠️ В `apps/creds.json` пароль лежит **открытым текстом**: файл в `apps/.gitignore` — не коммитить и не пересылать.
Провайдер берётся из реестра: источник и версия заданы в `pg/main.tf` и `apps/main.tf`.
Все команды выполняются из каталога `TEST_STAND/CRUD`.
Подробности дальше: что задавать руками, как всё устроено, что делать при ошибке.
## Что создаётся
@@ -97,15 +123,11 @@ cd ../apps && cp terraform.tfvars.example terraform.tfvars
| `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`, а провайдер ищет
инстанс **по имени внутри своего сервиса** (`provider/internal/resources_core/crud.go:171`,
`provider/internal/core/refsvc_find.go:47`). Если такое имя уже занято, он не станет создавать
инстанс **по имени внутри своего сервиса**. Если такое имя уже занято, он не станет создавать
новый ресурс, а **усыновит** существующий — то есть при занятом имени можно подцепить чужой или
старый инстанс. Если усыновление отключено, `apply` упадёт с «инстанс с resource_name … уже
существует».
Живой пример: прежние имена `tflucee`, `tfflask`, `tfnodejs` заняты старыми инстансами,
поэтому в стенде взяты `lucee-crud`, `flask-crud`, `nodejs-crud` (`apps/locals.tf:45,57,68`).
### Можно не задавать (есть значения по умолчанию)
`pg/main.tf`: `pg_cpu=500`, `pg_memory=512`, `pg_replicas=1`, `pg_disk=10`, `pg_version="17"`,
@@ -131,68 +153,6 @@ provider "nubes" {
}
```
## Запуск — четыре шага
### 1. База данных (`pg/`)
```bash
cd pg
cp terraform.tfvars.example terraform.tfvars
terraform init
terraform apply
```
Создадутся кластер (несколько минут), пользователь БД и база.
Обязательные значения — `api_token`, `realm`, `s3_name`. Полный список и правила по именам —
в разделе «Что пользователь задаёт сам» выше.
### 2. Передать креды БД в `apps/`
```bash
# всё ещё в папке pg/
terraform output -json > ../apps/creds.json
```
Одна команда выгружает хост, порт, имя пользователя, имя БД и пароль в `apps/creds.json`.
Приложения читают этот файл (`apps/locals.tf`).
!!! warning "В `creds.json` пароль лежит открытым текстом"
Файл в `apps/.gitignore` — не коммитить и не пересылать.
### 3. Приложения (`apps/`)
```bash
cd ../apps
cp terraform.tfvars.example terraform.tfvars
terraform init
terraform apply
```
Создадутся три приложения, подключённые к общей БД.
Обязательные значения — `api_token` и `realm` (те же, что в `pg/`). Имена доменов и имена
ресурсов приложений задаются в `apps/locals.tf` — см. раздел «Что пользователь задаёт сам».
### 4. Проверить
Откройте в браузере три адреса (это полные домены, которые платформа построила из имён в
`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> |
Свои адреса можно посмотреть в state:
```bash
grep -o 'https://[a-z0-9.-]*\.dev\.nubes\.ru' apps/terraform.tfstate | sort -u
```
Добавьте запись в одном приложении — она появится в двух других (таблица `crud_items` общая).
## Справка: выходные параметры `pg/`
В `pg/outputs.tf` объявлено шесть выходов:
@@ -248,18 +208,4 @@ pg_pass = local.creds.pg_password.value
- **`postgres_conf`** — ключи строго как в спецификации платформы: `paramName` / `paramValue`
(camelCase). Допустимы только `log_connections` и `log_disconnections`.
- **`realm`** — рабочая ресурсная платформа. Если у неё нет ёмкости, операция падает
с сообщением «Невозможно развернуть приложение в данной ресурсной платформе» — смотрите
журнал операции, а не только текст ошибки.
## Диагностика, если `apply` упал
Текст ошибки в `errorLog` у платформы **не всегда отражает суть**. Реальная причина — в журнале
операции:
```bash
GET {api_endpoint}/instanceOperations/<UID>?fields=cfsParams,errorLog,stages
```
`stages[].stageMsg` — массив пар `[заголовок, лог]`, смотреть последнюю запись. Там же
`cfsParams` — фактический набор параметров, ушедший на платформу. Разбор реального случая:
`HISTORY/60_stands/2026-10-01_test_crud_pg_create_failure.md`.
с сообщением «Невозможно развернуть приложение в данной ресурсной платформе».