tf_provider/HISTORY/2026-09-03_docs_upload_pipeline_verified.md

2026-09-03 — Проверенный pipeline публикации документации

Цель

Зафиксировать фактический pipeline публикации заново сгенерированной документации провайдера, чтобы не восстанавливать его заново по догадкам.

Источник документации

Для стенда <stand> используются только сгенерированные страницы:

generated/<stand>/docs/

Ручной каталог docs/ не используется как основной docs_dir. Скрипт 04_build_and_publish_docs.sh перед сборкой копирует в сгенерированный каталог только общие материалы:

docs/30_registry/
docs/curated/

После копирования в 30_registry/guides/getting-started.md подставляются параметры конкретного стенда:

• namespace;
• версия провайдера;
• API endpoint.

Актуальные скрипты

Генерация Markdown выполняется так:

TOOLS/scripts/01_generate_yamls.sh
  -> generated/<stand>/resources_yaml/

TOOLS/scripts/02_generate_resources_and_docs_v2.sh
  -> generated/<stand>/docs/

Сборка сайта выполняется скриптом:

TOOLS/scripts/04_build_and_publish_docs.sh --profile TOOLS/config/<stand>

Он создаёт временный .mkdocs.tmp.yml, задаёт site_url с namespace стенда, запускает MkDocs и создаёт:

site/

В конце этот скрипт вызывает актуальный:

./scripts/publish-docs.sh site "$REGISTRY_HOST" "$NAMESPACE" "$PROVIDER_NAME" "$VERSION"

Фактическое хранилище документации

Документация хранится не в bucket бинарников провайдера. Используется отдельный bucket:

terraform-registry

Публикация выполняется без версии. Для любого стенда целевой S3 prefix:

terraform-registry/docs/<namespace>/nubes/

Актуальный scripts/publish-docs.sh использует:

mc mirror --overwrite --remove site/ registry/terraform-registry/docs/<namespace>/nubes/

Следствие: в URL документации нет версии 2.0.0, 3.0.0 или 1.0.0.

Где выполнять S3 upload

История commit 9e02b69 зафиксировала, что из локальной сети большие рекурсивные операции S3 нестабильны. Поэтому mc mirror для документации выполняется на ВМ:

5.172.178.213

Проверенный порядок:

1. Собрать site/ локально.
2. Передать site/ на ВМ в ~/tmp-docs-site/.
3. На ВМ выполнить:
   mc mirror --overwrite --remove \
     ~/tmp-docs-site/ \
     registry/terraform-registry/docs/<namespace>/nubes/
4. На ВМ обновить локальное зеркало:
   mc mirror --overwrite --remove \
     registry/terraform-registry/docs/<namespace>/nubes/ \
     /var/www/tf-docs/<namespace>/

S3 upload и обновление зеркала — два отдельных действия. Одной загрузки в S3 недостаточно, если публичный proxy читает локальное зеркало ВМ.

Публичная доставка

На ВМ nginx использует корень:

/var/www/tf-docs/

Сервис tf_docs проксирует публичный домен на ВМ. Для любого стенда итоговый путь:

/var/www/tf-docs/<namespace>/

Итоговый URL любого стенда:

https://tf-docs.nodejsk8s.dev.nubes.ru/<namespace>/

Например, для DEV <namespace> равен nubes-dev, но это только значение профиля, а не отдельная логика pipeline.

Путь с версией не используется для любого стенда:

https://tf-docs.nodejsk8s.dev.nubes.ru/<namespace>/<version>/

не является корректным URL документации.

Важное различие с публикацией бинарников

Бинарники Terraform-провайдера публикуются в другом bucket и с версионным prefix:

nubes-terraform-registry/
  tf-registry.containerk8s.services.ngcloud.ru/
    <namespace>/nubes/<version>/

Документация публикуется отдельно:

terraform-registry/docs/<namespace>/nubes/

Не смешивать эти два pipeline.

Legacy, который не использовать

DOCS_PIPELINE/publish-docs.sh

Это справочная legacy-копия старого скрипта. Она использует старую схему mc cp, старую структуру и версионный путь. Для текущей публикации использовать:

scripts/publish-docs.sh

История изменений, подтверждающая схему

• dc469c6 — публикация docs без версии, mc mirror, site_url по стенду.
• 72a8a49 — актуализация README и новый docs host; старый скрипт помечен legacy.
• 9e02b69 — зафиксирована загрузка S3 с ВМ и обновление зеркала /var/www/tf-docs/.
• 02b7d7b — подстановка namespace, версии и API endpoint выполняется после копирования 30_registry в стендовый generated docs каталог.