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 terraform-registry
• Префикс: docs//// для документации, отдельный префикс для бинарников по правилам registry-сервера

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

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

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

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

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.

Credentials и VM

S3 credentials не хранятся в registry.env и не должны попадать в командную строку или документацию. Источники рабочего ключа:

• локально: secrets/.s3cfg_registry;
• на VM 5.172.178.213: /home/naeel/.mc/config.json;
• SSH-ключ к VM: ~/.ssh/naeel_vm_id_ed25519.

VM использовалась для прежних публикаций и содержит aliases registry, reg, tfreg и nubes. Проверка bucket без вывода секретов:

mc ls registry/terraform-registry

Нельзя заменять bucket на nubes-terraform-registry: у рабочего ключа нет прав на этот bucket. Симптом ошибки — Insufficient permissions to access this path на стадии mc cp; сборка provider при этом уже может быть успешной.

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

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

1. В выводе есть Done. Version <version> uploaded. и exit code 0.
2. В generated/<stand>/provider_build/ присутствуют ZIP, SHA256SUMS и .sig.
3. Объекты видны в точном S3 prefix через mc ls.

Если публикация прервалась во время 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