add: documentation

2026-06-30 15:45:24 +04:00
parent 540c1f7293
commit ca276d200f
1055 changed files with 47294 additions and 0 deletions
@@ -0,0 +1,55 @@
+# Troubleshooting Note: GPG, Terraform Custom Registry & Alpine
+
+Этот документ описывает технические нюансы и "грабли", обнаруженные при отладке Registry Protocol 23.01.2026.
+
+## 1. Ошибки Terraform GPG
+
+### `authentication signature from unknown issuer`
+**Симптом**: Terraform скачивает провайдер, но отказывается его устанавливать.
+**Механизм**:
+1. `terraform init` запрашивает у Registry URL для скачивания.
+2. Registry возвращает JSON, в котором есть поле `signing_keys` (массив public keys).
+3. Terraform скачивает `.sig` файл и `.zip` файл.
+4. Terraform проверяет, соответствует ли подпись `.sig` одному из ключей полученных из JSON.
+**Решение**: Публичный ключ, "зашитый" в код Registry Server, должен СТРОГО соответствовать приватному ключу, которым выполняется `gpg --detach-sign`.
+
+Практический чек-лист:
+1. Сгенерируйте ключи и сохраните `secrets/private_key.asc` и `secrets/public_key.asc`.
+2. Обновите ASCII Armor блока публичного ключа в:
+	- `registry-server-build/main.go`
+	- `operator/cmd/registry/main.go`
+3. Пересоберите и задеплойте registry server.
+4. Пересоберите и перезагрузите артефакты провайдера.
+
+### `error checking signature: openpgp: invalid data: tag byte does not have MSB set`
+**Симптом**: Terraform считает подпись битой.
+**Причина**: Формат файла подписи.
+- Если файл называется `.asc`, Terraform ожидает ASCII Armor (`-----BEGIN PGP...`).
+- Если файл называется `.sig`, Terraform (в некоторых версиях/контекстах) ожидает **бинарный** OpenPGP формат.
+**Решение**:
+Для файлов `.sig` создавайте бинарную подпись:
+`gpg --detach-sign ...` (БЕЗ `--armor`).
+
+---
+
+## 2. Проблемы запуска Go бинарников в Alpine
+
+### `exec /path/to/binary: no such file or directory`
+**Симптом**: Файл существует (проверено через ls), права на исполнение есть (+x), но при запуске ядро выдает "файл не найден".
+**Причина**: Бинарник скомпилирован динамически и требует динамический линковщик (например, `/lib64/ld-linux-x86-64.so.2`), которого нет в Alpine Linux (там используется `musl`, а не `glibc`).
+**Решение**:
+Компилировать Go приложения **абсолютно статически**:
+```bash
+CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -a -installsuffix cgo -ldflags '-extldflags "-static"' .
+```
+
+---
+
+## 3. Паттерн "Hot Deployment" (InitContainer Injection)
+
+Если нет доступа к Docker Registry, но нужно обновить код в запущенном кластере:
+1. Скомпилируйте бинарник локально.
+2. Загрузите его в S3.
+3. Используйте `initContainer` в Pod'е для скачивания бинарника в `emptyDir` volume.
+4. Смонтируйте этот volume в основной контейнер.
+5. Переопределите `command` основного контейнера, чтобы запускать скачанный файл.