Terraform Provider Nubes — карта проекта

Репозиторий содержит Terraform-провайдер Nubes Cloud и всю обвязку вокруг него: генераторы (API → YAML → Go), пайплайн сборки/заливки, документацию, стенды и служебные материалы.

Облачная платформа — VMware Cloud Director; сервисы Nubes (vcOrg, vcVdc, vcNsxt, k8s…) создают объекты в ней. Провайдер генерируется из спецификаций API, а не пишется руками.

---

🚦 Быстрая навигация

Что нужно	Куда идти
Инструкции: сборка, заливка, добавление сервиса	HOW_TO/ ← начинать отсюда
Пароль БД / секреты Vault (PostgreSQL)	docs/curated/postgres/pg_user_db.md — откуда брать пароль и почему нужен второй apply
Рабочие материалы: планы, промпты, анализы, выжимки чатов	NOTES/
Пользовательская документация (mkdocs)	docs/
Архив по датам и разборам	HISTORY/
Пайплайн публикации документации	DOCS_PIPELINE/README.md
Залитые версии провайдера (источник правды)	VERSIONS.md
Правила генерации кода (обязательны для генератора)	TOOLS/ARCHITECTURE.md
Правила работы для агента	.github/copilot-instructions.md
Текущая задача (IaC + modify)	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
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
В plan вместо значения печатается (sensitive value)	Переменная помечена sensitive = true без необходимости (realm, s3_uid). Секрет — только api_token	TEST_STAND/CRUD/main.tf

---

Как собрать и залить провайдер (кратко)

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/DEVOPS_BUILD_PIPELINE.md (полный ранбук + GPG-bootstrap) · 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/ — это отменённые («ложные») пути.