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,75 @@
+# AI Context: Terraform Registry Operator System Mechanics
+
+> **Цель файла:** Быстрая загрузка контекста для AI-агентов. Содержит карту компонентов, контракты данных и скрытые зависимости.
+
+## 1. Идентификация Системы
+*   **Тип:** Kubernetes Operator (Custom Controller).
+*   **Задача:** Автоматическая CI/CD сборка Terraform-провайдеров из Git-исходников и публикация в S3-совместимый реестр.
+*   **Текущий статус:** MVP (Fully working).
+
+## 2. Карта Файлов и Компонентов
+
+| Component | Source Path | Kubernetes Manifest | Docker Image | Key Function |
+|-----------|-------------|---------------------|--------------|--------------|
+| **Operator** | `cmd/main.go` | `04-operator-deployment.yaml` | `naeel/terraform-registry-operator` | Watch CRD -> Spawn Job -> Update Status |
+| **Registry API** | `cmd/registry/main.go` | `05-registry-server.yaml` | `naeel/terraform-registry-server` | Serve Terraform Discovery Protocol over S3 |
+| **Builder Job** | `manifests/03-build-script.yaml` | `04-operator-deployment.yaml` (managed) | `golang:1.24-alpine` (runtime) | Git Clone -> Go Build -> Upload to S3 |
+| **CRD** | `N/A` | `02-crd.yaml` | N/A | Kind: `TerraformProviderRelease`, Group: `terra.core.nubes.ru` |
+| **Storage** | `N/A` | `N/A` | `Nubes Cloud S3` | Artifact storage |
+
+## 3. Критические Контракты и Данные
+
+### 3.1. Переменные Окружения (ENV)
+*   **`REGISTRY_HOSTNAME`**: Ключевая переменная.
+    *   Где задается: `Deployment` (operator & registry-server).
+    *   Значение по умолчанию: `terra.k8c.ru`.
+    *   Влияние:
+        *   **Operator**: Передает это значение в Job.
+        *   **Job**: Использует как часть пути в S3 (`bucket/HOSTNAME/...`).
+        *   **Registry API**: Использует для фильтрации объектов в S3 и формирования ссылок.
+    *   **ВАЖНО:** Если изменить Hostname, старые артефакты в S3 станут "невидимыми", так как изменится префикс пути.
+
+### 3.2. Структура S3
+Бакет: `terraform-providers`
+Схема пути: `{hostname}/{namespace}/{provider_name}/{version}/{file}`
+Пример: `terra.k8c.ru/hashicorp/scaffolding/0.0.1/terraform-provider-scaffolding_0.0.1_linux_amd64.zip`
+
+### 3.3. RBAC (Security)
+*   Оператор работает от имени SA `terraform-operator`.
+*   Role: требует прав `create` на `jobs` и `update` на `providerreleases/status`.
+*   При пересборке манифестов **не терять** `00-rbac.yaml`.
+
+## 4. Алгоритм Работы (Logic Flow)
+
+```mermaid
+graph TD
+    A[User creates CR] -->|Watch| B(Operator)
+    B -->|Create| C[K8s Job]
+    C -->|Environment| D{REGISTRY_HOSTNAME}
+    C -->|Clone & Build| E[Artifacts .zip]
+    E -->|Upload| F[(S3)]
+    F -.->|Read| G(Registry Server)
+    G -.->|Discovery| H[Terraform CLI]
+```
+
+## 5. Ограничения (Tech Debt / MVP Constraints)
+1.  **GPG Signing:** Сейчас фейковое (создается пустой файл `.sig`). Для продакшена нужно внедрить реальный GPG key в Secret и монтировать в Job.
+2.  **Platform Support:** Жестко зашито в `build.sh`: `linux_amd64`, `windows_amd64`. Чтобы добавить (например, `darwin_arm64`), нужно править ConfigMap `builder-script`.
+3.  **Storage:** Используется внешнее S3, данные не зависят от жизненного цикла подов.
+4.  **Logging:** Оператор пишет в stdout, но нет структурированных логов (JSON).
+
+## 6. Команды для Оператора (Cheat Sheet)
+
+```bash
+# Сборка и Пуш
+cd operator && make push-all
+
+# Обновление логики сборки (без пересборки образов)
+kubectl apply -f manifests/03-build-script.yaml
+
+# Перезапуск оператора (чтобы подхватил изменения, если не используем :latest правильно)
+kubectl rollout restart deploy/terraform-operator -n terra
+
+# Проверка логов билда
+kubectl logs -f job/build-{name} -n terra
+```