tf_provider/docs/help/build-and-publish.md

Билд и публикация

1. Сборка провайдера (universal_rebuild)

Общий цикл:

1. Генерация YAML параметров для сервиса (service_params_gen).
2. Генерация Go-ресурсов (tools/gen).
3. Сборка бинарника go build.

Ключевые каталоги:

• universal_rebuild/resources_yaml
• universal_rebuild/internal/resources_gen
• universal_rebuild/tools/gen

2. Публикация провайдера в Registry

• Артефакты: zip, SHA256SUMS, SHA256SUMS.sig
• Подпись: для .sig использовать бинарную detached подпись
• Хранилище бинарников: S3 bucket nubes-terraform-registry
• Хранилище документации: S3 bucket terraform-registry (public)
• Префикс: docs/<namespace>/<name>/ для документации, <host>/<namespace>/<name>/<version>/ для бинарников

Канонический provider release workflow

Рабочий registry для provider-бинарников использует:

• Registry hostname: tf-registry.containerk8s.services.ngcloud.ru;
• S3 endpoint: https://s3.msk-1.ngcloud.ru;
• S3 bucket: nubes-terraform-registry;
• DEV namespace: nubes-dev;
• Provider name: nubes.

Для DEV version 2.0.1 полный путь бинарников:

nubes-terraform-registry/tf-registry.containerk8s.services.ngcloud.ru/nubes-dev/nubes/2.0.1/

Публикация выполняется из корня репозитория одной командой:

cd /home/naeel/TF/tf_provider
REQUEST_DELAY=0.05 ATTEMPTS=3 \
	./TOOLS/scripts/03_build_and_upload_provider.sh \
	--profile TOOLS/config/dev 2.0.1

03_build_and_upload_provider.sh перед сборкой автоматически запускает 01 и 02, поэтому отдельно запускать генераторы для обычного release не требуется. В результате создаются:

• generated/dev/resources_yaml/ — актуальные YAML из DEV API;
• generated/dev/go/ — generated Go, включая *_modifier.go и registry.go;
• generated/dev/docs/ — generated docs;
• generated/dev/provider_build/ — три ZIP, SHA256SUMS и SHA256SUMS.sig.

Перед upload скрипт проверяет, что каждый constructor из resource/modifier/action-файлов присутствует в registry.go, затем собирает provider для linux/amd64, windows/amd64 и darwin/amd64.

Разделение S3-хранилищ и Credentials

В архитектуре используются два разных бакета S3:

1. Бинарники провайдеров:
   • Бакет: nubes-terraform-registry
   • Права на заливку: аккаунт 1112_terraform:super (secrets/.s3cfg_provider, алиас prod-s3)
   • Чтение: реестр читает через встроенный аккаунт 1112_terraform:reader (6DDP5...)
2. MkDocs-документация:
   • Бакет: terraform-registry (публичный)
   • Права на заливку: аккаунт 1325 (secrets/.s3cfg_registry, алиас registry)

Нельзя путать эти бакеты: заливка бинарников в terraform-registry делает версию невидимой для реестра, а попытка залить бинарники ключом документации вызывает ошибку прав доступа (Insufficient permissions).

Контроль успешной публикации

Успех подтверждается только после всех трёх условий:

1. В выводе есть Done. Version <version> uploaded. и exit code 0.
2. В generated/<stand>/provider_build/ присутствуют ZIP, SHA256SUMS и .sig.
3. Объекты видны в точном S3 prefix через mc ls prod-s3/nubes-terraform-registry/....
4. Запрос curl https://tf-registry.containerk8s.services.ngcloud.ru/v1/providers/<namespace>/<name>/versions возвращает новую версию в списке.

Если публикация прервалась во время 01, повторный запуск безопасен: он только читает service specs из API и перезаписывает generated YAML. Terraform apply, modify и delete для публикации не запускаются.

Важное про GPG ключи

• Приватный ключ должен быть стабильным между релизами.
• Если ключ перевыпущен, обнови публичный ключ в registry server (ASCII Armor в registry-server-build/main.go и operator/cmd/registry/main.go) и задеплой сервис.
• Иначе terraform init упадет с authentication signature from unknown issuer.

One-time bootstrap

1. Сгенерируй и экспортируй ключи в secrets/.
2. Вставь ASCII Armor публичного ключа в:
   • registry-server-build/main.go
   • operator/cmd/registry/main.go
3. Пересобери и задеплой registry server.
4. Пересобери и загрузите артефакты провайдера.

3. Документация (MkDocs)

Сборка

• Использовать Docker образ squidfunk/mkdocs-material
• Результат: директория site/

Публикация

• Использовать scripts/publish-docs.sh
• Путь в S3: docs////

4. Важные нюансы

• При смене домена обновлять registry и ключи подписи.
• Пресайнд URL через Ingress может ломаться — использовать proxy mode.
• В документации исключены технические папки, не предназначенные для публикации.

5. Операции (non-CRUD)

• Ops YAML (для всех операций): ./devops/01b_generate_ops_yamls.sh
• Документация операций: ./devops/02b_generate_ops_docs.sh