Repinoid
2aa2946700
Перенос в тематические папки сломал бы все ссылки, поэтому обновлены пути:
- HISTORY/OPUS/ -> HISTORY/90_llm/OPUS/, HISTORY/SONNET/ -> HISTORY/90_llm/SONNET/;
- 15 целевых файлов из корня получили свой тематический префикс
(HISTORY/<файл>.md -> HISTORY/<папка>/<файл>.md) — в 33 файлах репозитория.
Затронуто вне HISTORY: README.md, VERSIONS.md, HOW_TO/DEVOPS_BUILD_PIPELINE.md,
NOTES/README.md, NOTES/10_plans/, NOTES/20_prompts/, NOTES/30_analysis/,
NOTES/40_chat_summaries/, docs/curated/{crud,postgres}, docs/help/dev-reference/,
docs/ops/TESTING.md.
Проверки после правки:
- ссылок вида HISTORY/<дата> без тематической папки не осталось;
- все пути HISTORY/*.md из markdown-ссылок существуют (кроме трёх упоминаний,
которые не были файлами и до переноса: HISTORY/90_llm/OPUS/3006_1.md,
3006_0.md — планировавшиеся имена в старых транскриптах,
и HISTORY/HOWTO-UPLOAD.md — ссылка на старый внешний репозиторий tf_registry);
- ссылки по «голому» имени внутри 90_llm/OPUS/ остались корректными (соседние файлы).
143 lines
11 KiB
Markdown
143 lines
11 KiB
Markdown
# Terraform Provider Nubes — карта проекта
|
||
|
||
Репозиторий содержит **Terraform-провайдер Nubes Cloud** и всю обвязку вокруг него:
|
||
генераторы (API → YAML → Go), пайплайн сборки/заливки, документацию, стенды и служебные материалы.
|
||
|
||
Облачная платформа — **VMware Cloud Director**; сервисы Nubes (`vcOrg`, `vcVdc`, `vcNsxt`, `k8s…`)
|
||
создают объекты в ней. Провайдер генерируется из спецификаций API, а не пишется руками.
|
||
|
||
---
|
||
|
||
## 🚦 Быстрая навигация
|
||
|
||
| Что нужно | Куда идти |
|
||
|---|---|
|
||
| **Инструкции: сборка, заливка, добавление сервиса** | **[`HOW_TO/`](HOW_TO/README.md)** ← начинать отсюда |
|
||
| **Пароль БД / секреты Vault (PostgreSQL)** | **[`docs/curated/postgres/pg_user_db.md`](docs/curated/postgres/pg_user_db.md)** — откуда брать пароль и почему нужен второй `apply` |
|
||
| Рабочие материалы: планы, промпты, анализы, выжимки чатов | [`NOTES/`](NOTES/README.md) |
|
||
| Пользовательская документация (mkdocs) | [`docs/`](docs/README.md) |
|
||
| Архив по датам и разборам | [`HISTORY/`](HISTORY/) |
|
||
| Пайплайн публикации документации | [`DOCS_PIPELINE/README.md`](DOCS_PIPELINE/README.md) |
|
||
| Залитые версии провайдера (источник правды) | [`VERSIONS.md`](VERSIONS.md) |
|
||
| Правила генерации кода (обязательны для генератора) | [`TOOLS/ARCHITECTURE.md`](TOOLS/ARCHITECTURE.md) |
|
||
| Правила работы для агента | [`.github/copilot-instructions.md`](.github/copilot-instructions.md) |
|
||
| Текущая задача (IaC + `modify`) | [`NOTES/40_chat_summaries/CHAT_RESUME_IAC_2026-09-24.md`](NOTES/40_chat_summaries/CHAT_RESUME_IAC_2026-09-24.md) |
|
||
|
||
---
|
||
|
||
## ⚠️ Грабли, на которые уже наступали (чтобы не искать заново)
|
||
|
||
| Симптом | Что на самом деле | Где смотреть |
|
||
|---|---|---|
|
||
| `Invalid index ... The given key does not identify an element in this collection value` в `locals` приложений (Lucee/Flask/Node.js) | Пароль БД читается из `vault_secrets["users"]`, а он пуст, если PostgreSQL и пользователь создаются **одним** `apply`. Нужны **два apply** | [`docs/curated/postgres/pg_user_db.md`](docs/curated/postgres/pg_user_db.md) |
|
||
| `errorLog` операции не совпадает с сутью («Invalid JSON String» и подобное) | Реальная причина — в `stages`: `GET {api_endpoint}/instanceOperations/<UID>?fields=cfsParams,errorLog,stages` | [`HISTORY/60_stands/2026-10-01_test_crud_pg_create_failure.md`](HISTORY/60_stands/2026-10-01_test_crud_pg_create_failure.md) |
|
||
| В `plan` вместо значения печатается `(sensitive value)` | Переменная помечена `sensitive = true` без необходимости (`realm`, `s3_uid`). Секрет — только `api_token` | `TEST_STAND/CRUD/main.tf` |
|
||
|
||
---
|
||
|
||
## Как собрать и залить провайдер (кратко)
|
||
|
||
```bash
|
||
cd /home/naeel/TF/tf_provider
|
||
|
||
# 1) YAML-спеки из API стенда
|
||
./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/dev
|
||
# 2) YAML → Go-ресурсы + документация
|
||
./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/dev
|
||
# 3) Сборка (linux/windows/darwin) + GPG-подпись + заливка в S3
|
||
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/dev 2.0.18
|
||
# 4) (опционально) публикация документации
|
||
./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/dev 2.0.18
|
||
```
|
||
|
||
**Подробные инструкции:**
|
||
[`HOW_TO/HOWTO-UPLOAD.md`](HOW_TO/HOWTO-UPLOAD.md) (сборка/заливка) ·
|
||
[`HOW_TO/DEVOPS_BUILD_PIPELINE.md`](HOW_TO/DEVOPS_BUILD_PIPELINE.md) (полный ранбук + GPG-bootstrap) ·
|
||
[`HOW_TO/HOWTO_ADD_NEW_SERVICE.md`](HOW_TO/HOWTO_ADD_NEW_SERVICE.md) (новый сервис).
|
||
|
||
**Схема версий (жёстко):** `prod = 1.*`, `dev = 2.*`, `test = 3.*`.
|
||
Легаси (`prod=2.*`, `dev=3.*`, `test=5.*`, `0.0.1`) — не использовать.
|
||
|
||
---
|
||
|
||
## Структура репозитория
|
||
|
||
| Путь | Что это |
|
||
|---|---|
|
||
| **`HOW_TO/`** | **Все общие инструкции:** сборка/заливка, пайплайн, добавление сервиса, миграция, генерация доков. Индекс: `HOW_TO/README.md` |
|
||
| **`NOTES/`** | Рабочие материалы: `10_plans`, `20_prompts`, `30_analysis`, `40_chat_summaries`, `60_reference`. Карта: `NOTES/README.md` |
|
||
| **`docs/`** | Документация: публикуемый сайт (mkdocs) + внутренние разделы (см. ниже) |
|
||
| **`DOCS_PIPELINE/`** | Пайплайн публикации сайта документации (`publish-docs.sh`) |
|
||
| **`HISTORY/`** | Архив по датам (`HISTORY/90_llm/OPUS/`, `HISTORY/90_llm/SONNET/`) — хроника решений и разборов |
|
||
| **`TOOLS/`** | Генераторы и скрипты: `yaml-generator` (API→YAML), `resource-generator` (YAML→Go), `docs-generator`, `scripts/`, `config/`, `lib/`. Правила: `TOOLS/ARCHITECTURE.md` |
|
||
| **`provider/`** | Исходники самого провайдера (ядро, CRUD-хелперы, `main.go`) |
|
||
| **`generated/`** | Машинный выхлоп: `generated/<стенд>/resources_yaml`, `/go`, `/docs`, `/provider_build` |
|
||
| **`DEV_STAND/`, `TEST_STAND/`, `PROD_STAND/`** | Terraform-манифесты стендов (проверочные конфигурации, `sync.sh`) |
|
||
| **`HAR/`** | HAR-дампы live-запросов к API (сырые данные для анализа) |
|
||
| **`secrets/`** | Токены стендов, GPG-ключи, S3-креды. **Не коммитить** |
|
||
| **`gateway/`, `apps/`, `charts/`** | Вспомогательный сервис/приложения/чарты (вне ядра провайдера) |
|
||
| **`tf_examples/`, `tfflaskcrud/`, `tfluceecrud/`, `tfnodejscrud/`** | Примеры конфигураций Terraform |
|
||
| **`! /`** | Прецедент Cloud Director (чужой tf-код на официальном `terraform-provider-vcd`) — образец «как надо» |
|
||
| **`TMP/`** | Временное/бэкапы |
|
||
| `mkdocs.yml`, `site/`, `site_test/` | Конфиг и вывод сборки сайта документации |
|
||
|
||
---
|
||
|
||
## Документация: `docs/`
|
||
|
||
Собирается mkdocs (`mkdocs.yml`, nav → `docs/`). Разделы:
|
||
|
||
| Раздел | Что внутри |
|
||
|---|---|
|
||
| `docs/index.md`, `docs/30_registry/` | **Публикуется**: главная, справочник ресурсов, руководства, ассеты |
|
||
| `docs/curated/` | Проверенные примеры (напр. `postgres/pg_user_db.md`) |
|
||
| `docs/90_finance/` | Финансовые шаблоны (акт) |
|
||
| `docs/ops/` | Операционные runbook'и: `API_TOKENS.md`, `STANDS.md`, `MONITORING.md`, `ROLLBACK.md`, `RUNBOOK.md`, `TESTING.md` |
|
||
| `docs/help/` | Внутренние справки: `BUILD.md`, `build-and-publish.md`, `architecture-and-methods.md`, `error-knowledge-base.md`, `dev-reference/` |
|
||
| `docs/00_overview/`, `docs/20_discovery/`, `docs/40_analysis/`, `docs/50_history/`, `docs/60_strategy/`, `docs/70_api/` | Внутренние разделы (исключены из сайта: `exclude_docs` в `mkdocs.yml`) |
|
||
| `docs/TODO/` | Технические заметки «что не сделано» |
|
||
|
||
---
|
||
|
||
## Пайплайн (что происходит под капотом)
|
||
|
||
```
|
||
API стенда ──01──▶ generated/<стенд>/resources_yaml/*.yaml (yaml-generator)
|
||
│
|
||
├──02──▶ generated/<стенд>/go/*.go (resource-generator + registry)
|
||
│ generated/<стенд>/docs/*.md (docs-generator)
|
||
│
|
||
├──03──▶ сборка linux/windows/darwin → GPG-подпись → S3-реестр
|
||
└──04──▶ mkdocs build → публикация документации
|
||
```
|
||
|
||
Ключевое: **схема tf-ресурса строится из операции `create`** в YAML, а ID операций/параметров
|
||
сохраняются из API. Нюансы и известные ограничения — в `NOTES/30_analysis/` и `NOTES/README.md`.
|
||
|
||
---
|
||
|
||
## Стенды и реестр
|
||
|
||
| Стенд | Namespace | Диапазон версий | Профиль |
|
||
|---|---|---|---|
|
||
| PROD | `nubes` | `1.*` | `TOOLS/config/prod` |
|
||
| DEV | `nubes-dev` | `2.*` | `TOOLS/config/dev` |
|
||
| TEST | `nubes-test` | `3.*` | `TOOLS/config/test` |
|
||
|
||
- Реестр: `tf-registry.containerk8s.services.ngcloud.ru`; бакет бинарников `nubes-terraform-registry`.
|
||
- Общий конфиг реестра: `TOOLS/config/registry.env`; стенд-специфика: `TOOLS/config/<стенд>/profile.env`
|
||
(`NUBES_API_ENDPOINT`, `TOKEN_FILE`, `NAMESPACE`, `VERSION`).
|
||
- Список сервисов для генерации: `TOOLS/config/<стенд>/services_list.txt` (у каждого стенда свой;
|
||
общего списка нет — см. `HISTORY/40_generator/2026-09-30_yaml_pipeline_hardening.md`).
|
||
|
||
---
|
||
|
||
## ⛔ Чего не делать
|
||
|
||
- **Не использовать** легаси-схемы версий (`prod=2.*`, `dev=3.*`, `test=5.*`, `0.0.1`).
|
||
- **Не использовать** закрытые API и хосты: `index.cfm`, `registry.kube5s.ru`, `deck-api.ngcloud.ru`.
|
||
- **Не вызывать** старые бинарники из `TOOLS/*/bin/` — скрипты пересобирают генераторы сами.
|
||
- **Не перегенерировать GPG-ключ** подписи — сломается `terraform init` у пользователей.
|
||
- **Не путать бакеты:** бинарники `nubes-terraform-registry`, документация `terraform-registry`.
|
||
- **Не опираться** на файлы с баннером ⛔ в `NOTES/` и `HISTORY/` — это отменённые («ложные») пути.
|