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

## 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/<namespace>/<name>/<version>/ для документации, отдельный префикс для бинарников по правилам 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` полный путь бинарников:

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

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

```bash
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 без вывода секретов:

```bash
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/<namespace>/<name>/<version>/

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

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