# Документация провайдера Nubes: генерация и публикация

> Актуально на 2026-09-03. Историческая версия — [`README.legacy.md`](./README.legacy.md).

## Общая схема

```
API стенда ──▶ generated/<стенд>/resources_yaml/ ──▶ generated/<стенд>/docs/ (.md)
                                                        │  (docs_dir для MkDocs)
                                                        ▼
                                              MkDocs build ──▶ site/ (HTML)
                                                        │
                                                        ▼
                              S3 terraform-registry/docs/<namespace>/<name>/   (без версии, public)
                                                        │
                                                        ▼
                       ВМ 5.172.178.213 nginx (зеркало /var/www/tf-docs/) ◀─ под tf_docs (proxy)
                                                        │
                                                        ▼
                        https://tf-docs.nodejsk8s.dev.nubes.ru/<namespace>/
```

Ключевые принципы:
- **Без версий в URL**: docs публикуются в `docs/<namespace>/<name>/` перезаписью (`mc mirror --overwrite --remove`).
- **Вечный бесплатный домен**: `tf-docs.nodejsk8s.dev.nubes.ru/<namespace>/` (managed-кластер → под-прокси → ВМ nginx).
- Имя провайдера (`<name>`) во всех стендах — `nubes`; в URL сайта не фигурирует (только `<namespace>`), в S3-ключе — есть.

## Стенды

| Стенд | profile.env | Namespace (S3/URL) | API-эндпоинт | Токен |
|---|---|---|---|---|
| dev | `TOOLS/config/dev/profile.env` | `nubes-dev` | `https://lk-api-gateway-dev.ngcloud.ru/api/v1/svc` | `secrets/dev.token` |
| test | `TOOLS/config/test/profile.env` | `nubes-test` | `https://lk-api-gateway-test.ngcloud.ru/api/v1/svc` | `secrets/test.token` |
| prod | `TOOLS/config/prod/profile.env` | `nubes` | `https://lk-api-gateway.ngcloud.ru/api/v1/svc` | `secrets/prod.token` |

В `profile.env` также: `PROVIDER_NAME=nubes`, пути GPG-ключей, актуальная `VERSION` стенда.

## Нумерация версий провайдера по стендам

> ⛔ **ЕДИНСТВЕННАЯ схема (с 2026-09-03).** Старые диапазоны (`prod=2.*`, `dev=3.*`,
> `test=5.*`, а также `0.0.x`) — ЛЕГАСИ, **НЕ ИСПОЛЬЗОВАТЬ**. Полная чистка реестра
> выполнена 2026-09-03 — старые версии удалены из S3.

| Стенд | Диапазон версий | Первая |
|---|---|---|
| **prod** (`nubes`) | `1.*.*` | `1.0.0` |
| **dev** (`nubes-dev`) | `2.*.*` | `2.0.0` |
| **test** (`nubes-test`) | `3.*.*` | `3.0.0` |

Версия передаётся аргументом в `03_build_and_upload_provider.sh <ver>` и хранится в
`VERSION` в `profile.env`. Источник правды — [`VERSIONS.md`](../../VERSIONS.md).

## Поток A — генерация Markdown (API → YAML → .md)

| Шаг | Скрипт | Результат |
|---|---|---|
| 1 | `TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/<стенд>` | спецификации ресурсов из API → `generated/<стенд>/resources_yaml/` |
| 2 | `TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/<стенд>` | YAML → Go-код провайдера + Markdown-доки → `generated/<стенд>/docs/` (в т.ч. `_nav_fragment.yml`) |
| 3 (опц.) | `TOOLS/scripts/05_generate_docs_llm.py` | LLM-улучшение описаний `.md` |
| 4 | `TOOLS/scripts/03_build_and_upload_provider.sh --profile ... <ver>` | сборка провайдера + GPG-подпись + бинарники в S3 (не docs) |

## Поток B — сборка MkDocs-сайта и публикация

| Шаг | Скрипт | Что делает |
|---|---|---|
| 1 | `TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/<стенд> [ver]` | собирает сайт и публикует (см. ниже) |
| 2 | `scripts/publish-docs.sh <site> <host> <ns> <name>` | заливка `site/` в S3 (см. ниже) |
| 3 (опц.) | `scripts/publish-doc-page.sh` | заливка одной страницы |
| CI | `.github/workflows/publish-docs.yml` | авто-публикация по git-тегу `v*.*.*` |

### Детали шага 04

1. Читает `profile.env` стенда (`--profile`): `NAMESPACE`, `VERSION`, `NUBES_API_ENDPOINT`, `REGISTRY_HOST` (default `tf-docs.nodejsk8s.dev.nubes.ru`).
2. `MKDOCS_DOCS_DIR` = `generated/<стенд>/docs` — **никогда не сливается с ручным `docs/`**.
3. Копирует ручные ассеты в сгенерированный каталог: `docs/30_registry/` и `docs/curated/` → `generated/<стенд>/docs/`.
4. Подставляет в `generated/<стенд>/docs/guides/getting-started.md` актуальные `version` и `api_endpoint`.
5. Генерирует `.mkdocs.tmp.yml` из `mkdocs.yml`:
   - `site_url: https://<REGISTRY_HOST>/<NAMESPACE>/`;
   - `docs_dir` — относительный на `generated/<стенд>/docs`;
   - в `nav` секция «Ресурсы» заменяется на `resources_nav` из `_nav_fragment.yml`.
6. Сборка в `site/` (по убыванию приоритета): docker `squidfunk/mkdocs-material` → `.venv` python mkdocs → системный `mkdocs`. Пинованные версии: `mkdocs==1.6.1`, `mkdocs-material==9.7.3`.
7. Заливка: `./scripts/publish-docs.sh site "$REGISTRY_HOST" "$NAMESPACE" "$PROVIDER_NAME" "$VERSION"`.
   - ⚠️ `publish-docs.sh` принимает 4 аргумента (`site host ns name`); 5-й (`VERSION`) игнорируется — публикация всегда без версии.

### Детали publish-docs.sh (актуальный)

- Берёт S3-креды из `S3_ENDPOINT/S3_ACCESS_KEY/S3_SECRET_KEY` (или legacy `MINIO_*`), при вызове из `04` — подгружаются из `secrets/.s3cfg_registry`.
- `mc alias set registry <endpoint> <ak> <sk> --api S3v4`.
- `mc mirror --overwrite --remove "$SITE_DIR/" → registry/terraform-registry/docs/<namespace>/<name>/`.
- `mc policy set public` на target.
- Публикация «на месте»: старые файлы удаляются, версий нет.

## Промежуточные файлы и папки

| Папка/файл | Назначение |
|---|---|
| `generated/<стенд>/resources_yaml/` | сырые YAML-спеки из API (шаг A1) |
| `generated/<стенд>/docs/` | сгенерированные Markdown + `_nav_fragment.yml` (docs_dir для MkDocs) |
| `site/` | результат сборки MkDocs (HTML), заливается в S3 |
| `site_test/` | тестовая сборка по `.mkdocs.docs_test.yml` |
| `docs/` | ручные источники (`index.md`, `curated/`, `help/`, `30_registry/`); внутренние разделы (`00_overview`, `20_discovery`, `40_analysis`, `50_history`, `60_strategy`, `70_api`, `help/*`, `README.md`, `ai_universal_provider_gen.md`) исключаются через `exclude_docs` |
| `scripts/publish-docs.sh` | актуальная заливка docs в S3 (без версии) |
| `scripts/publish-doc-page.sh` | заливка одной страницы |
| `TOOLS/config/<стенд>/profile.env` | параметры стенда (endpoint, NAMESPACE, VERSION, токен, GPG) |
| `TOOLS/config/registry.env`, `services_list.txt`, `operation_timeouts.json` | конфиги реестра/генерации |
| `TOOLS/bin/` | генераторы: `resource-generator`, `docs-generator`, `yaml-generator` |
| `secrets/{dev,test,prod}.token`, `.s3cfg_registry`, `private_key.asc` | токены API, S3-креды, GPG |
| `mkdocs.yml` | базовый конфиг MkDocs (тема material, exclude_docs, extra) |
| `.mkdocs.tmp.yml` | генерируется в 04, удаляется по trap |
| `.mkdocs.docs_test.yml` | конфиг тестовой сборки (site_test) |
| `DOCS_PIPELINE/publish-docs.sh` | ⚠️ легаси-копия старого скрипта (с версией, `mc cp`); **не использовать** |

## S3 и хостинг

| Что | Бакет | Ключ |
|---|---|---|
| Документация | `terraform-registry` (public) | `docs/<namespace>/<name>/` — без версии |
| Бинарники провайдера | `nubes-terraform-registry` | `<host>/<namespace>/<name>/<version>/` |

- S3-эндпоинт: `https://s3.msk-1.ngcloud.ru` (Ceph RGW). Клиент `mc` (алиасы `prod-s3`/`reg`/`registry`/`tfreg`).
- Доставка до браузера: S3 → ВМ-зеркало (`/var/www/tf-docs/`) → nginx ВМ отдаёт `/<namespace>/` → под `tf_docs` (reverse-proxy в кластере) → `https://tf-docs.nodejsk8s.dev.nubes.ru/<namespace>/`.
- ВМ отдаёт также по прямому IP `http://5.172.178.213/<namespace>/`.

## Требования к окружению (настроено 2026-09-03)

Чтобы пайплайн работал **штатно и не ломался**, на машине сборки должно быть:

| Компонент | Как проверить | Что ставить |
|---|---|---|
| `python3-venv` (Debian/Ubuntu) | `python3 -m venv /tmp/v && ls /tmp/v/bin/pip` | `sudo apt install -y python3.12-venv` — без него venv создаётся БЕЗ pip |
| `.venv` проекта с mkdocs | `.venv/bin/python -m mkdocs --version` | пересоздать: `rm -rf .venv && python3 -m venv .venv && .venv/bin/pip install mkdocs==1.6.1 mkdocs-material==9.7.3` |
| Системный mkdocs (запасной) | `python3 -m mkdocs --version` | `pip3 install --user mkdocs==1.6.1 mkdocs-material==9.7.3` |
| `mc` (MinIO client) | `mc --version` | см. docs min.io |
| docker + образ `squidfunk/mkdocs-material` (запасной) | `docker images` | `docker pull squidfunk/mkdocs-material` |

> **Почему так.** `04` при `--profile` собирает через `.venv` проекта. Если `.venv` пустой/сломан (нет pip/mkdocs) — сборка падает. Корень: без системного пакета `python3.12-venv` виртуальное окружение создаётся без `pip`/`ensurepip`. Это чинится один раз (apt + пересоздание `.venv`), дальше не ломается.
> Версии зафиксированы: `mkdocs==1.6.1`, `mkdocs-material==9.7.3` (совпадают и в системном python3, и в `.venv`).

## Публикация: где запускать `mc mirror`

S3 (`s3.msk-1.ngcloud.ru`) из локальной сети **рвёт большие ответы** (рекурсивный листинг >нескольких сотен объектов зависает: `mc: Unable to list ... unexpected EOF`; малые `mc ls`/`mc cp` работают). Поэтому **заливку на S3 делать с ВМ `5.172.178.213`** — у неё быстрый канал до S3 (~10 МБ/с).

Полный цикл публикации стенда (сборка локально → S3 с ВМ → зеркало на ВМ):

```bash
# 1. Сборка (локально, штатно)
./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/test 5.0.8
#    (если site/ собирался docker-ом от root — mkdocs не сможет его перезаписать:
#     sudo rm -rf site  или  docker run --rm -v $PWD:/docs --entrypoint rm squidfunk/mkdocs-material -rf /docs/site)

# 2. Передать собранный site/ на ВМ
tar -C site -cf - . | ssh naeel@5.172.178.213 'rm -rf ~/tmp-docs-site && mkdir -p ~/tmp-docs-site && tar -C ~/tmp-docs-site -xf -'

# 3. Залить на S3 с ВМ (быстрый канал)
ssh naeel@5.172.178.213 'mc mirror --overwrite --remove ~/tmp-docs-site/ registry/terraform-registry/docs/nubes-test/nubes/'

# 4. Обновить зеркало /var/www/tf-docs (откуда nginx отдаёт сайт)
ssh naeel@5.172.178.213 'mc mirror --overwrite --remove "registry/terraform-registry/docs/nubes-test/nubes/" /var/www/tf-docs/nubes-test/'
```

> ⚠️ Если `mc mirror`/`mc ls -r` локально зависает — это не баг скрипта, а сеть до S3; заливать с ВМ.

## Быстрые команды

```bash
# Полный цикл для стенда dev
./TOOLS/scripts/01_generate_yamls.sh --profile TOOLS/config/dev
./TOOLS/scripts/02_generate_resources_and_docs_v2.sh --profile TOOLS/config/dev
./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/dev

# Только пересборка и публикация (YAML/Go не менялись)
./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/test

# Ручная заливка уже собранного site/
scripts/publish-docs.sh site tf-docs.nodejsk8s.dev.nubes.ru nubes-test nubes
```