# 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).
    *   Значение по умолчанию: `registry.kube5s.ru  <!-- ⛔ LEGACY: registry.kube5s.ru ЗАКРЫТ. Актуальный хост: tf-registry.containerk8s.services.ngcloud.ru -->  <!-- ⛔ LEGACY: registry.kube5s.ru  <!-- ⛔ LEGACY: registry.kube5s.ru ЗАКРЫТ. Актуальный хост: tf-registry.containerk8s.services.ngcloud.ru --> ЗАКРЫТ. Актуальный хост: tf-registry.containerk8s.services.ngcloud.ru -->`.
    *   Влияние:
        *   **Operator**: Передает это значение в Job.
        *   **Job**: Использует как часть пути в S3 (`bucket/HOSTNAME/...`).
        *   **Registry API**: Использует для фильтрации объектов в S3 и формирования ссылок.
    *   **ВАЖНО:** Если изменить Hostname, старые артефакты в S3 станут "невидимыми", так как изменится префикс пути.

### 3.2. Структура S3
Бакет: `terraform-providers`
Схема пути: `{hostname}/{namespace}/{provider_name}/{version}/{file}`
Пример: `registry.kube5s.ru  <!-- ⛔ LEGACY: registry.kube5s.ru ЗАКРЫТ. Актуальный хост: tf-registry.containerk8s.services.ngcloud.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
```