tf_provider/DOCS_PIPELINE

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

Актуально на 2026-09-03. Историческая версия — 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.

Поток 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 с ВМ → зеркало на ВМ):

# 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; заливать с ВМ.

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

# Полный цикл для стенда 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