177 lines
13 KiB
Markdown
177 lines
13 KiB
Markdown
# Документация провайдера 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
|
||
```
|