terraform/tf_provider
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: актуализация DOCS_PIPELINE/README (без версий, новый хост); старый -> legacy

Browse Source
This commit is contained in:
“Naeel”
2026-09-03 07:27:58 +03:00
parent dc469c6dce
commit 72a8a491c6
2 changed files with 237 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DOCS_PIPELINE/README.md
+103 -115
View File
@@ -1,134 +1,122 @@
# Документация MkDocs: генерация и заливка в реестр
# Документация провайдера Nubes: генерация и публикация
> ⛔⛔⛔ **НЕ ЛОМАТЬ РАБОТАЮЩИЙ КОД** ⛔⛔⛔
>
> Эта папка — **справочная**. Скрипты пайплайна в `TOOLS/scripts/` и `scripts/`
> работают и должны оставаться **нетронутыми**.
> Любая правка в них — только после явного «делай» и с проверкой, что ничего не сломалось.
> Актуально на 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>/
```
Всё про **генерацию документации** провайдера Nubes, **сборку** MkDocs-сайта
и **заливку** статики в S3-реестр.
Ключевые принципы:
- **Без версий в URL**: docs публикуются в `docs/<namespace>/<name>/` перезаписью (`mc mirror --overwrite --remove`).
- **Вечный бесплатный домен**: `tf-docs.nodejsk8s.dev.nubes.ru/<namespace>/` (managed-кластер → под-прокси → ВМ nginx).
- Имя провайдера (`<name>`) во всех стендах — `nubes`; в URL сайта не фигурирует (только `<namespace>`), в S3-ключе — есть.
## Два независимых потока
## Стенды
### A. Генерация Markdown-доков по ресурсам (API → YAML → .md)
| Стенд | 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` стенда.
## Поток 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/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-код (`TOOLS/bin/resource-generator`) + Markdown-доки (`TOOLS/bin/docs-generator`) в `generated/<стенд>/docs/` |
| 3 (опц.) | `TOOLS/scripts/05_generate_docs_llm.py` | Прогоняет .md через LLM (улучшение описаний) |
| 4 | `TOOLS/scripts/03_build_and_upload_provider.sh --profile ... <ver>` | Сборка провайдера + GPG-подпись + заливка бинарников в S3 |
| 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*.*.*` |
### B. Сборка MkDocs-сайта + заливка доков в S3
### Детали шага 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 и хостинг
| Что | Бакет | Ключ |
|---|---|---|
| 1 | `TOOLS/scripts/04_build_and_publish_docs.sh --profile ... <ver>` | Генерирует `.mkdocs.tmp.yml` (версия/`docs_dir`/nav), собирает сайт (docker → venv → system mkdocs) в `site/` |
| 2 | `scripts/publish-docs.sh` | Заливает `site/` в S3 (`mc cp --recursive` + `mc policy set public`) |
| 3 (опц.) | `scripts/publish-doc-page.sh` | Заливка **одной** страницы |
| CI | `.github/workflows/publish-docs.yml` | Авто-публикация по git-тегу `v*.*.*` |
| Документация | `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>/`.
## Команды (полный цикл, стенд = dev/test/prod)
## Быстрые команды
```bash
# DEV (пример)
# Полный цикл для стенда 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/03_build_and_upload_provider.sh --profile TOOLS/config/dev 3.1.13
./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/dev 3.1.13
./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
```
**Быстрая заливка** (YAML/Go уже сгенерированы, не менялись) — только шаг 3/4:
```bash
./TOOLS/scripts/03_build_and_upload_provider.sh --profile TOOLS/config/test 5.1.17
./TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/test 5.1.17
```
### Ручная заливка доков (рабочий способ)
```bash
# S3-креды из secrets/.s3cfg_registry (или env S3_ENDPOINT/S3_ACCESS_KEY/S3_SECRET_KEY)
/home/naeel/terra/scripts/publish-docs.sh \
site \
tf-registry.containerk8s.services.ngcloud.ru \
nubes nubes 2.0.2
```
---
## Список файлов
### Скрипты (пайплайн)
- `TOOLS/scripts/01_generate_yamls.sh`
- `TOOLS/scripts/02_generate_resources_and_docs_v2.sh`
- `TOOLS/scripts/03_build_and_upload_provider.sh`
- `TOOLS/scripts/04_build_and_publish_docs.sh`
- `TOOLS/scripts/05_generate_docs_llm.py`
- `TOOLS/scripts/build-provider.sh`
- `scripts/publish-doc-page.sh`
- `scripts/publish-docs.sh` ← ⚠️ см. «Известная проблема» ниже
### Генераторы (Go-бинарники)
- `TOOLS/bin/resource-generator`
- `TOOLS/bin/docs-generator`
- `TOOLS/bin/yaml-generator`
### Конфиг
- `mkdocs.yml` — конфиг MkDocs (site_url, nav, тема material)
- `TOOLS/config/registry.env` — реестр (`REGISTRY_HOSTNAME`, `S3_ENDPOINT`, `S3_BUCKET`)
- `TOOLS/config/{dev,test,prod}/profile.env` — стенд (`NUBES_API_ENDPOINT`, `NAMESPACE`, `VERSION`)
- `TOOLS/config/{dev,test,prod}/services_list.txt`
- `TOOLS/config/{dev,test,prod}/operation_timeouts.json`
### Секреты
- `secrets/{dev,test,prod}.token`
- `secrets/private_key.asc` — GPG-подпись
- `secrets/.s3cfg_registry` — S3-креды
### Контент / ассеты
- `docs/` — ручные источники (`index.md`, `curated/`, `help/`, `30_registry/` и др.)
- `docs/30_registry/` — `guides/`, `resources/`, `assets/`, `javascripts/fix-slash.js`
- `generated/<стенд>/docs/` — сгенерированные доки (включая `_nav_fragment.yml`)
- `site/`, `site_test/` — результат сборки
---
## S3 / бакеты
| Что | Бакет | Путь |
|---|---|---|
| **Документация** | `terraform-registry` | `docs/<namespace>/<name>/<version>/` |
| **Бинарники провайдера** | `nubes-terraform-registry` | `<host>/<namespace>/<name>/<version>/` |
- Эндпоинт S3: `https://s3.msk-1.ngcloud.ru`
- Хост реестра: `tf-registry.containerk8s.services.ngcloud.ru`
- Клиент: `mc` (MinIO), алиасы `prod-s3`/`reg`/`registry`/`tfreg`
---
## ⚠️ Известная проблема: `scripts/publish-docs.sh` отсутствует в этом репозитории
1. Скрипт `scripts/publish-docs.sh` **удалён** из `/home/naeel/tf_provider`
коммитом `c2438f5` (2026-07-05, «superseded by devops/»).
2. Но `TOOLS/scripts/04_build_and_publish_docs.sh` (строка ~280) и
`.github/workflows/publish-docs.yml` (строка ~54) **до сих пор вызывают**
`./scripts/publish-docs.sh`.
3. **Следствие:** запуск `04` из этого репозитория соберёт сайт, но упадёт
на шаге заливки (`No such file or directory`). CI по тегу — аналогично.
**Рабочая копия скрипта живёт в старом репозитории** (отдельный git, не клон):
- `/home/naeel/terra/scripts/publish-docs.sh`
- архив: `/home/naeel/terraform__OFF/scripts/publish-docs.sh`
Копия этого скрипта сохранена рядом: [`publish-docs.sh`](./publish-docs.sh)
### Варианты устранения (только после «делай»)
1. Восстановить `scripts/publish-docs.sh` в это репозиторий (из копии рядом или из git `c2438f5^`).
2. Инлайнить заливку прямо в `04_build_and_publish_docs.sh` (как уже сделано в `publish-doc-page.sh`).