Repinoid
cbd559d767
- TOOLS/README.md: раздел «Канонический пайплайн (порядок шагов)» и описание безопасной генерации (staging → атомарная замена, бэкапы, маркер .stand); - TOOLS/ARCHITECTURE.md: ссылки devops/… → TOOLS/config/<stand>/…; - HISTORY/2026-09-30_yaml_pipeline_hardening.md: полная история изменений (что было не так, что сделано, прогон по стендам, коммиты, проверки).
100 lines
4.4 KiB
Markdown
100 lines
4.4 KiB
Markdown
# TOOLS — Генераторы Terraform-провайдера Nubes
|
|
|
|
Каждый инструмент — независимый Go-модуль.
|
|
|
|
## Канонический пайплайн (порядок шагов)
|
|
|
|
```bash
|
|
# 1) YAML-спеки сервисов из API (per-stand!)
|
|
./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/dev
|
|
|
|
# 2) Go-ресурсы + документация из этих YAML
|
|
./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/dev
|
|
|
|
# 3) (релиз) сборка 3 платформ + публикация в реестр
|
|
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev
|
|
```
|
|
|
|
`--profile` обязателен: без него скрипты выходят с кодом 2 (никаких дефолтов).
|
|
|
|
### Шаг 1 — безопасная генерация YAML
|
|
|
|
`01_generate_yamls.sh` работает по принципу «сначала во временное, потом атомарная замена»:
|
|
|
|
- генерация идёт в staging-каталог `generated/<stand>/resources_yaml.staging.<pid>/`;
|
|
- рабочий `generated/<stand>/resources_yaml/` **не** удаляется и **не** модифицируется до полного успеха;
|
|
- при полном успехе старый каталог уезжает в бэкап `resources_yaml.bak-<UTC>`,
|
|
а staging встаёт на его место (атомарный `mv` в пределах одного FS),
|
|
хранятся последние `KEEP_BACKUPS` (по умолчанию 5);
|
|
- при любой ошибке замена **отменяется**: старый каталог цел, частичный результат лежит в staging для разбора, скрипт выходит с кодом 1;
|
|
- в каталоге лежит маркер `.stand`, защищающий от генерации не в тот стенд.
|
|
|
|
Перегенерировать все стенды подряд:
|
|
|
|
```bash
|
|
for s in dev test prod; do
|
|
./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/$s || break
|
|
done
|
|
```
|
|
|
|
> Примечание: часть параметров API отдаёт со случайным `default`-суффиксом
|
|
> (`db-ievgpdvu` → `db-ujama5rb` и т.п.), поэтому побайтовое сравнение двух
|
|
> прогонов даёт различия в этих строках — это не регрессия.
|
|
|
|
## yaml-generator
|
|
|
|
API Nubes → `resources_yaml/*.yaml`
|
|
|
|
```bash
|
|
cd yaml-generator && go build -o ../bin/yaml-generator .
|
|
./bin/yaml-generator
|
|
```
|
|
|
|
Структура: `main.go` + `internal/{client,config,normalize,spec,types}`.
|
|
|
|
## resource-generator
|
|
|
|
`resources_yaml/*.yaml` → `internal/resources_gen/*.go` + `registry.go`
|
|
|
|
```bash
|
|
cd resource-generator && go build -o ../bin/resource-generator .
|
|
./bin/resource-generator
|
|
```
|
|
|
|
Структура: `main.go` + `internal/{helpers,loader,params,templates,types,writers}`.
|
|
|
|
### Как запускать правильно
|
|
|
|
Не запускайте `TOOLS/resource-generator/bin/resource-generator` вручную и не полагайтесь на старый бинарник из `TOOLS/resource-generator/bin/`.
|
|
|
|
Используйте канонический скрипт из корня репозитория, он **всегда** пересобирает генераторы из текущих исходников перед запуском:
|
|
|
|
```bash
|
|
./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/dev
|
|
```
|
|
|
|
Для других стендов подставляйте нужный профиль:
|
|
|
|
```bash
|
|
./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/test
|
|
./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/prod
|
|
```
|
|
|
|
Это устраняет случайный запуск устаревшего бинаря и гарантирует, что новые `kind` из YAML, включая `modifier`, будут обработаны текущим кодом генератора.
|
|
|
|
## docs-generator
|
|
|
|
`resources_yaml/*.yaml` → Markdown-документация в `docs/30_registry/resources/`
|
|
|
|
```bash
|
|
cd docs-generator && go build -o ../bin/docs-generator .
|
|
|
|
# Документация ресурсов
|
|
./bin/docs-generator
|
|
|
|
# Operations-документация
|
|
./bin/docs-generator --ops
|
|
```
|
|
|
|
Структура: `main.go` + `internal/{types,writers,ops}`.
|