123 lines
9.0 KiB
Markdown
123 lines
9.0 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` стенда.
|
||
|
||
## Поток 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>/`.
|
||
|
||
## Быстрые команды
|
||
|
||
```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
|
||
```
|