110 lines
6.2 KiB
Markdown
110 lines
6.2 KiB
Markdown
# Билд и публикация
|
||
|
||
## 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` полный путь бинарников:
|
||
|
||
```text
|
||
nubes-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`.
|
||
|
||
### Разделение 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/<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`
|