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

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

Цель

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

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

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

generated/<stand>/docs/

Для DEV:

generated/dev/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

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

terraform-registry/docs/nubes-dev/nubes/

Для остальных стендов:

terraform-registry/docs/nubes-test/nubes/
terraform-registry/docs/nubes/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 проксирует публичный домен на ВМ. Для DEV итоговый путь:

/var/www/tf-docs/nubes-dev/

Итоговый URL DEV:

https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-dev/

Путь с версией не используется:

https://tf-docs.nodejsk8s.dev.nubes.ru/nubes-dev/2.0.0/

не является корректным 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 каталог.