diff --git a/TEST_STAND/POSTGRES/main.tf b/TEST_STAND/POSTGRES/main.tf index 8ce5485..46cca82 100644 --- a/TEST_STAND/POSTGRES/main.tf +++ b/TEST_STAND/POSTGRES/main.tf @@ -1,8 +1,8 @@ terraform { required_providers { nubes = { - source = "terra.k8c.ru/nubes/nubes" - version = "5.0.52" + source = "terra.k8c.ru/nubes-test/nubes" + version = "5.0.75" } } } diff --git a/TEST_STAND/buck0/main.tf b/TEST_STAND/buck0/main.tf index 86da992..382d7cd 100644 --- a/TEST_STAND/buck0/main.tf +++ b/TEST_STAND/buck0/main.tf @@ -14,8 +14,8 @@ provider "nubes" { } # S3 bucket — замени "buck0" на своё имя везде ниже -resource "nubes_s3bucket" "buck0" { # ← замени buck0 на своё имя ресурса - resource_name = "buck0" # ← замени buck0 на своё имя ресурса +resource "nubes_s3bucket" "bukka" { # ← замени buck0 на своё имя ресурса + resource_name = "Бакет тест1" # ← замени buck0 на своё имя ресурса s3_user_uid = var.s3_user_uid bucket_name = "buck0" # ← замени buck0 на своё имя бакета } diff --git a/docs/TODO/resource_name_docs.md b/docs/TODO/resource_name_docs.md new file mode 100644 index 0000000..2f3ce60 --- /dev/null +++ b/docs/TODO/resource_name_docs.md @@ -0,0 +1,26 @@ +# `resource_name` в документации — план доработок + +## Суть проблемы +- `resource_name` — **Required: true** во всех 82+ сгенерированных ресурсах +- Хардкодится в Go-шаблоне: `universal_rebuild/tools/gen_v2/generate_resources_v2.go:911` +- Мапится на API-поле `displayName` (CRUD: `universal_rebuild/internal/resources_core/crud.go:30`) +- В сгенерированной документации (`docs/30_registry/resources/*.md`) — **отсутствует полностью** +- Нет ни в HCL-примерах, ни в таблицах параметров + +## Причина +Docs-генератор (`universal_rebuild/tools/docs_template_gen_v2/main.go`) читает только YAML-спеки, а `resource_name` — не API-параметр create-операции, его нет в YAML. Это мета-параметр уровня провайдера. + +## Что править +**Один файл:** `universal_rebuild/tools/docs_template_gen_v2/main.go` + +1. **`exampleBlock()`** (~строка 373) — добавить `resource_name = "my-instance"` первой строкой в resource-блок +2. **`buildCreateParamsPage()`** (~строка 411) — добавить секцию «Системные параметры» с описанием `resource_name` перед таблицей create-параметров + +## Почему не YAML +- `resource_name` — не API-параметр, это уровень Terraform-провайдера +- Добавление в 42 YAML-спека семантически неверно + легко забыть при новых сервисах +- Правильнее зеркально Go-генератору: один раз в docs-генераторе → охват всех ресурсов + +## Чеклист +- [ ] `resource_name` в HCL-примерах (exampleBlock) +- [ ] `resource_name` в таблицах create-параметров (buildCreateParamsPage) diff --git a/docs/help/dev-reference/INDEX.md b/docs/help/dev-reference/INDEX.md new file mode 100644 index 0000000..761574d --- /dev/null +++ b/docs/help/dev-reference/INDEX.md @@ -0,0 +1,79 @@ +# Справочник разработчика (Dev Reference) + +> Единый каталог проблем, решений, архитектурных решений и состояний провайдера. +> **Цель:** чтобы агенты и разработчики НЕ повторяли одни и те же ошибки. + +--- + +## Быстрый поиск + +| Если нужно | Иди в | +|-----------|-------| +| Найти баг по названию/симптому | `01_BUGS_ALL.md` | +| Найти баг по симптомам ("висит", "403", "inconsistent result") | `02_BUGS_BY_SYMPTOM.md` | +| Найти баг по категории (polling, auth, generation, adopt) | `03_BUGS_BY_CATEGORY.md` | +| Понять архитектуру (почему так сделано) | `04_ARCHITECTURE.md` | +| Понять состояния ресурсов (RUNNING, SUSPEND, DELETED) | `05_STATE_MATRIX.md` | +| **Агентам — прочитать ОБЯЗАТЕЛЬНО перед любыми правками** | `06_TLDR_FOR_AGENTS.md` | +| Как добавить новую запись | `INSTRUCTION.md` | + +--- + +## Алфавитный указатель терминов (см. `01_BUGS_ALL.md`) + +| Термин | Раздел в 01_BUGS_ALL | +|--------|---------------------| +| 400 Bad Request | C — Modify: Invalid CFS parameter | +| 401 Unauthorized | A — Authentication | +| 403 DDoS-Guard | A — DDoS-Guard 403 | +| 404 docs | K — Docs 404 | +| 500 VM modify | G — VM 500 String[]→GUID | +| adopt | L — Adopt/Resume | +| create-only params | Q — Create-only params modification | +| deleted filter | O — Deleted filter missing | +| detach semantics | P — Destroy/Detach semantics | +| disk decrease | R — Disk shrink | +| displayName duplicate | M — Duplicate displayNames | +| dtFinish | B — Polling hang | +| GPG unknown issuer | I — GPG unknown issuer | +| GPG invalid data | I — GPG invalid data | +| HTTP/2 EOF | A — HTTP/2 ALPN EOF | +| import | N — Import not implemented | +| map/json format | E — Map/JSON/List invalid format | +| operation_in_progress | L — Operation in progress | +| orphan instance | S — Orphan on create abort | +| polling hang | B — Polling hang | +| ref_svc_id deleted | O — Ref svc showing deleted | +| split() on null | H — Postgres split() on null | +| String[]→GUID | F — VM FW failure | +| subresource id unknown | T — Subresource id unknown | +| suspend_on_destroy | P — Destroy semantics | +| User-Agent | A — DDoS-Guard 403 | +| YAML stale | U — YAML stale/validation | + +--- + +## Статусы багов + +| Метка | Значение | +|-------|----------| +| ✅ FIXED | Исправлено, версия указана | +| ⚠️ OPEN | Не исправлено, известная проблема | +| ❌ WORKAROUND | Есть обходное решение, но баг не закрыт | +| 🟡 PLATFORM | Баг платформы/бэкенда, не провайдера | + +--- + +## Источники данных + +Справочник собран из: +- `docs/50_history/` (00-24) — история спринтов +- `HISTORY/OPUS/` — анализ Opus 4.8 +- `HISTORY/SONNET/0107.md` — debug DDoS-Guard +- `HISTORY/2026-07-01_ddos_guard_403_and_registry_fix.md` — фикс registry +- `docs/help/` — существующие глоссарии и error KB +- `docs/20_discovery/` — discovery-материалы +- `docs/60_strategy/` — стратегия и философия +- Исходный код `universal_rebuild/` + +Последнее обновление: 2026-07-01 diff --git a/docs/help/dev-reference/INSTRUCTION.md b/docs/help/dev-reference/INSTRUCTION.md new file mode 100644 index 0000000..1b5b95d --- /dev/null +++ b/docs/help/dev-reference/INSTRUCTION.md @@ -0,0 +1,68 @@ +# Инструкция: как добавить запись в справочник + +## Формат одной записи (шаблон) + +```markdown +## [P0/P1/P2] Короткое название проблемы +**Симптом:** что происходит, как проявляется +**Причина:** root cause +**Решение:** что сделали / что нужно сделать +**Статус:** ✅ FIXED / ⚠️ OPEN / ❌ WORKAROUND / 🟡 PLATFORM +**Версия:** vX.Y.Z (в какой версии исправлено, если есть) +**Файлы:** +- `путь/к/файлу.go:номер_строки` — что там +**Источники:** +- `docs/50_history/NN_*.md` — ссылка на историю +- `HISTORY/...` — если описание в HISTORY/ + +## Пример заполнения + +## [P0] POST 403 после DDoS-Guard +**Симптом:** terraform apply → HTTP 403 на POST запросах к ColdFusion API +**Причина:** DDoS-Guard блокирует запросы без User-Agent; %2F в URL ломает WAF +**Решение:** +1. `req.Header.Set("User-Agent", "Mozilla/5.0")` во всех HTTP-вызовах +2. `rawQuery := "endpoint=" + path` (без url.Values, чтобы не было %2F) +3. `TLSNextProto = make(map[string]func(...))` — отключить HTTP/2 ALPN +4. `transport.Proxy = nil` — не использовать HTTPS_PROXY +**Статус:** ⚠️ OPEN (User-Agent ✅ FIXED v5.0.75, POST всё ещё 403) +**Файлы:** +- `universal_rebuild/internal/core/client.go:865` — doRequest (User-Agent ✅) +- `universal_rebuild/internal/core/client.go:522` — FindExistingInstances (User-Agent ✅) +- `universal_rebuild/internal/core/client.go:597` — GetInstanceState (User-Agent ✅) +- `universal_rebuild/internal/core/client.go:644` — GetInstanceStateRaw (User-Agent ✅) +- `universal_rebuild/internal/resources_core/domain_collision.go:99` — коллизии доменов (User-Agent ✅) +- `devops/01_generate_yamls.sh` — urllib без User-Agent 🔴 +**Источники:** +- `HISTORY/SONNET/0107.md` +- `HISTORY/2026-07-01_ddos_guard_403_and_registry_fix.md` +``` + +## Правила + +1. **Каждый баг — одна запись.** Не группировать разные проблемы в одну. +2. **Симптом — конкретно:** что видит пользователь/агент (ошибка, код возврата, сообщение). +3. **Файлы — с номерами строк:** `universal_rebuild/internal/core/client.go:865` (без `L`). +4. **Статус — честно:** если не исправлено — ⚠️ OPEN. +5. **Ссылки на источники** — относительные пути от корня репы. +6. **Приоритет P0/P1/P2:** + - **P0** — блокирует работу (apply падает, data loss) + - **P1** — серьёзно мешает (wrong behaviour, needless calls) + - **P2** — улучшение/cleanup + +## Куда добавлять + +| Тип записи | Файл | +|-----------|------| +| Новый баг (любой) | `01_BUGS_ALL.md` (в конец раздела по букве/категории) | +| Новый симптом | `02_BUGS_BY_SYMPTOM.md` | +| Новая категория | `03_BUGS_BY_CATEGORY.md` | +| Архитектурное решение | `04_ARCHITECTURE.md` | +| Новое состояние | `05_STATE_MATRIX.md` | +| Критичное для агентов | `06_TLDR_FOR_AGENTS.md` | + +## После добавления + +1. Проверить что ссылки валидны (файлы существуют, строки примерно верны) +2. Обновить `INDEX.md` — алфавитный указатель +3. `git add + git commit + git push` diff --git a/docs/help/dev-reference/PLAN_FOR_NEW_CHAT.md b/docs/help/dev-reference/PLAN_FOR_NEW_CHAT.md new file mode 100644 index 0000000..2f6d440 --- /dev/null +++ b/docs/help/dev-reference/PLAN_FOR_NEW_CHAT.md @@ -0,0 +1,215 @@ +# ПЛАН: Создание общего справочника разработчика + +> Этот файл — инструкция для нового чата. +> Прочитать перед началом работы. + +--- + +## 1. Задача + +Создать единый справочник разработчика по ВСЕМ проектам, чтобы: +- Агенты не повторяли одни и те же ошибки +- Было удобно искать по любой теме/симптому +- Было удобно добавлять новые записи + +## 2. Где разместить + +**Вариант A (рекомендую):** `/home/naeel/global-dev-reference/` + +Отдельная директория в `~`. Плюсы: +- Не привязана к одному репозиторию +- Агент видит файлы если workspace открыт на `/home/naeel/` +- Можно проинициализировать git (опционально) +- Можно сделать символическую ссылку из каждого проекта + +**Вариант B:** В `docs/help/dev-reference/` внутри tf_provider. +- Минус: другие проекты не увидят. +- Минус: привязано к одному репо. + +## 3. Какие проекты включить + +| Проект | Путь | Что содержит | +|--------|------|-------------| +| **tf_provider** | `/home/naeel/tf_provider/` | Terraform provider (Universal + Legacy), docs/, HISTORY/ | +| **contracts** | `/home/naeel/nubes/contracts/` | Проект contracts | +| **ipwhitelist** | `/home/naeel/ipwhitelist/` | Проект ipwhitelist | +| **ВМ 5.172.178.213** | SSH: `naeel@5.172.178.213` | Registry-server, старые скрипты, история | +| **terra/** | `/home/naeel/terra/` | Старые проекты (fission, IoT, karta, lang...) | + +## 4. Структура справочника + +``` +/home/naeel/global-dev-reference/ +├── INDEX.md # Оглавление + алфавитный указатель +├── INSTRUCTION.md # Как добавлять новую запись +├── TLDR_FOR_AGENTS.md # Агентам — прочитать ОБЯЗАТЕЛЬНО +│ +├── projects/ # По проектам +│ ├── tf_provider/ +│ │ ├── BUGS.md # Все баги tf_provider +│ │ ├── ARCHITECTURE.md # Ключевые архитектурные решения +│ │ ├── STATE_MATRIX.md # Матрица состояний инстансов +│ │ └── PARAM_MAP.md # Маппинг параметров create↔modify +│ ├── contracts/ +│ │ └── BUGS.md +│ ├── ipwhitelist/ +│ │ └── BUGS.md +│ └── registry-vm/ +│ └── BUGS.md +│ +└── cross-cutting/ # Сквозные темы (общие для всех проектов) + ├── AUTH.md # Проблемы аутентификации (токены, DDoS-Guard, GPG) + ├── POLLING.md # Паттерны polling (dtFinish, таймауты) + ├── DDS_GUARD.md # DDoS-Guard: где и как обходить + ├── GPG.md # GPG подписи: ключи, форматы, ошибки + ├── REGISTRY_PROTOCOL.md # Terraform Registry Protocol + └── SSH_AND_VM.md # Доступ к ВМ, sshfs, ключи +``` + +## 5. Формат одной записи (бага/решения) + +Каждый баг оформляется так: + +```markdown +## [P0] Короткое название +**Симптом:** что происходит, текст ошибки +**Причина:** root cause +**Решение:** что сделали/надо сделать +**Статус:** ✅ FIXED / ⚠️ OPEN / ❌ WORKAROUND / 🟡 PLATFORM +**Версия:** vX.Y.Z (где исправлено) +**Файлы:** +- `/абсолютный/путь/к/файлу.go:123` — что там +**Источники:** +- относительная ссылка на HISTORY файл +``` + +## 6. Что уже есть для tf_provider (ГОТОВЫЙ МАТЕРИАЛ) + +Уже собранные данные (можно сразу переносить): + +### Баги tf_provider (25+ штук): + +**A. Аутентификация и токены (P0)** +- 401 Unauthorized — токен истёк +- **403 DDoS-Guard (User-Agent)** — ✅ FIXED v5.0.75 +- **403 DDoS-Guard (POST)** — ⚠️ OPEN (причина не до конца ясна) +- **HTTP/2 ALPN EOF** — ✅ FIXED (TLSNextProto) + +**B. Поллинг зависает (P0)** +- Polling без dtFinish — ✅ FIXED (критерий dtFinish) +- Polling игнорирует Instance Status ERROR/STOPPED — ✅ FIXED (waitForVMOperationAndInstanceStatus) +- Polling не ловит асинхронные ошибки — ✅ FIXED (WaitForOperation) + +**C. Modify: Invalid CFS parameter 400 (P1)** +- Разные svcOperationCfsParamId для create и modify — ✅ FIXED (runtime discovery) + +**D. Modify недоступен (P1)** +- action modify not available — ✅ FIXED (guard через availableOperations) + +**E. Map/JSON/List invalid format 400 (P1)** +- Пустые строки вместо {} / [] — ✅ FIXED (V2-V6 нормализации) +- mapExample как `"\""` — ✅ FIXED (V6) + +**F. VM: зависание на FW (P0)** +- String[]→GUID crash — ❌ WORKAROUND (валидатор, баг платформы) +- accessIpList пустая строка — ✅ FIXED (ValidJSONArray + fallback) + +**G. VM modify: 500 checkParam (P1)** +- Дублирование параметров при POST/PUT — ✅ FIXED (гибридный PUT/POST) + +**H. Postgres: split() on null (P0)** +- Передан UUID бакета вместо UUID сервиса S3 — ✅ FIXED + +**I. GPG/Registry (P0)** +- authentication signature from unknown issuer — ✅ FIXED (синхронизация ключей) +- openpgp invalid data — ✅ FIXED (бинарная подпись без --armor) +- Presigned URL не работает через Ingress — ✅ FIXED (proxy mode) +- Registry Not Found (неполный ID) — ✅ FIXED +- GPG ключ в репозитории secrets/ — ⚠️ OPEN + +**J. Документация 404 (P1)** +- Неверный S3 ключ — ✅ FIXED (docs/ prefix) + +**K. Terraform Plugin Framework версии (P2)** +- Несовместимость framework и plugin-go — ✅ FIXED (v1.4.2 + v0.19.1) + +**L. Adopt/Resume (P1)** +- Ref-параметры не валидировались при adopt — ✅ FIXED v5.0.50 (ref_validation.go) +- Duplicate displayNames — ✅ FIXED v5.0.50 +- operation_in_progress — ✅ FIXED v5.0.50 + +**M. Сборка и CI (P1)** +- Missing resources_yaml embed — ✅ FIXED v5.0.1 +- Повторная установка mkdocs — ✅ FIXED v5.0.4 +- Сборочный контейнер без git/zip/curl — ✅ FIXED +- urllib без User-Agent (01_generate_yamls.sh) — ⚠️ OPEN +- urllib без обработки ошибок API — ⚠️ OPEN +- Нет retry в doRequest (429/503) — ⚠️ OPEN + +**N. Генерация (P1)** +- Неизвестный kind тихо игнорируется — ⚠️ OPEN +- YAML не валидируется — ⚠️ OPEN +- format.Source пишет битый код — ⚠️ OPEN +- Нет CI-диффа API vs YAML — ⚠️ OPEN +- YAML устарел (новые операции в API) — ⚠️ OPEN + +**O. Destroy/Detach (P1)** +- Destroy вызывал API delete для suspend-ресурсов — ✅ FIXED v5.0.8 + +**P. Create-only params (P1)** +- Needless modify при изменении create-only params — ✅ FIXED v5.0.38 + +**Q. Subresource id unknown (P1)** +- .id unknown после apply для subresource без modify — ✅ FIXED v5.0.7 + +**R. Deleted filter (P0)** +- План показывает deleted инстансы в ref_svc_id — ✅ FIXED v5.0.38 +- findInstanceUidByDisplayNameRefSvc без deleted filter — ✅ FIXED (в коде) +- Три разные функции строят запросы к /instances — ⚠️ OPEN (рефакторинг) + +**S. Orphan при обрыве (P0)** +- После POST /instances но до run — orphan not_created — ⚠️ OPEN + +**T. Тесты (P2)** +- Всего 8 unit-тестов — ⚠️ OPEN +- adopt, polling, генератор не покрыты — ⚠️ OPEN + +**U. Диск (P2)** +- Disk decrease rejected (скейл-даун) — 🟡 PLATFORM + +**V. Стенды (P1)** +- PROD_STAND/RABBIT указывает на test-endpoint — ⚠️ OPEN +- Legacy провайдер не используется — ⚠️ OPEN + +## 7. Источники данных (где лежит) + +Все баги собраны из: +- `/home/naeel/tf_provider/docs/50_history/` — файлы 00-24 +- `/home/naeel/tf_provider/HISTORY/OPUS/` — 7 файлов анализа +- `/home/naeel/tf_provider/HISTORY/SONNET/0107.md` +- `/home/naeel/tf_provider/HISTORY/2026-07-01_ddos_guard_403_and_registry_fix.md` +- `/home/naeel/tf_provider/docs/help/` — существующие глоссарии +- `/home/naeel/tf_provider/docs/20_discovery/` +- `/home/naeel/tf_provider/docs/60_strategy/` +- Анализ кода `universal_rebuild/` + +## 8. Порядок действий (для нового чата) + +1. Прочитать этот файл (PLAN_FOR_NEW_CHAT.md) +2. Прочитать INDEX.md и INSTRUCTION.md (уже созданы) +3. Решить где размещать: вариант A (~/global-dev-reference/) или вариант B (в tf_provider/docs/) +4. Создать структуру директорий +5. Наполнить BUGS.md для tf_provider (данные уже есть в п.6) +6. Прочитать contracts, ipwhitelist, ВМ — собрать их баги +7. Создать cross-cutting файлы (AUTH, POLLING, GPG...) +8. Написать TLDR_FOR_AGENTS.md +9. Если нужно — git init в global-dev-reference/ +10. Создать символические ссылки из проектов на справочник + +## 9. Ключевые требования + +- ⚡ **Каждый баг — ссылки на конкретные файлы и строки кода** +- ⚡ **Удобный поиск** — INDEX с алфавитным указателем +- ⚡ **лёгкое добавление** — INSTRUCTION с шаблоном +- ⚡ **Агенты не тупят** — TLDR_FOR_AGENTS.md обязателен к прочтению +- ⚡ **Статусы честные** — OPEN не прятать diff --git a/s.sh b/s.sh new file mode 100755 index 0000000..0bfbdb4 --- /dev/null +++ b/s.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash +set -euo pipefail + +VM_HOST="naeel@5.172.178.213" +VM_PATH="/home/naeel/tf_provider/TEST_STAND" +SSH_KEY="$HOME/.ssh/naeel_vm_id_ed25519" +SSH_OPTS="-o StrictHostKeyChecking=no -o ConnectTimeout=10" + +rsync -avz --delete \ + --exclude '.terraform/' \ + --exclude '*.tfstate' \ + --exclude '*.tfstate.*' \ + --exclude '.terraform.lock.hcl' \ + -e "ssh -i $SSH_KEY $SSH_OPTS" \ + /home/naeel/tf_provider/TEST_STAND/ \ + "${VM_HOST}:${VM_PATH}/"