# Terraform Infrastructure for Pulse Project

Этот репозиторий содержит инфраструктуру как код (IaC) для проекта Pulse, развернутого в Yandex Cloud.

## Архитектура

Проект использует **единый конфигурационный файл** `infrastructure.yaml` (аналог `values.yaml` в Helm), который описывает всю инфраструктуру декларативно. Модули Terraform универсальны и не знают про конкретные сущности - они используются для создания ресурсов, описанных в конфиге.

## Структура репозитория

```
.
├── infrastructure.yaml    # Единый конфигурационный файл (аналог values.yaml)
├── modules/              # Универсальные Terraform модули
│   ├── yc-s3/            # Модуль для создания S3 бакета
│   ├── yc-database/      # Модуль для работы с существующим PostgreSQL
│   ├── k8s-namespace/    # Модуль для создания Kubernetes namespace
│   └── k8s-secret/       # Модуль для создания Kubernetes секретов
└── live/                 # Живая инфраструктура
    ├── terragrunt.hcl    # Глобальная конфигурация Terragrunt
    └── stage/            # Окружение stage
        ├── env.hcl       # Конфигурация окружения
        ├── namespace/    # Namespace из конфига
        ├── s3/          # S3 бакет из конфига
        ├── database/    # База данных из конфига
        └── secrets/     # Секреты из конфига
```

## Конфигурационный файл

Все ресурсы описываются в `infrastructure.yaml`:

```yaml
environments:
  stage:
    namespaces:
      - name: pulse
        labels: {}
        annotations: {}
    
    secrets:
      - name: dockerhub
        namespace: pulse
        type: dockerconfigjson
        # ...
    
    buckets:
      - name: pulse
        acl: public-read
        # ...
    
    databases:
      - cluster_id: pg-stage  # ID существующего кластера
        database:
          name: pulse_db
        user:
          name: pulse
          password_length: 32
```

Каждый `terragrunt.hcl` читает этот конфиг через `yamldecode(file(...))` и извлекает нужные параметры.

## Модули

Все модули **универсальны** и не содержат хардкода про конкретные сущности:

- **yc-s3** - создает S3 бакет с любыми параметрами из конфига
- **yc-database** - работает с существующим PostgreSQL кластером, создает БД и пользователя
- **k8s-namespace** - создает namespace с любыми labels/annotations
- **k8s-secret** - создает секреты с поддержкой `lifecycle.ignore_changes`

## Особенности

### Секреты с защитой от перезаписи

Секреты могут быть настроены с `lifecycle.ignore_changes: true`, чтобы не перезаписываться после создания:

```yaml
secrets:
  - name: pulse-s3-secret
    lifecycle:
      ignore_changes: true
```

### Использование существующего PostgreSQL

Модуль `yc-database` работает с **существующим** кластером PostgreSQL в Yandex Cloud. Он только создает базу данных и пользователя, не создавая новый кластер.

### Зависимости между ресурсами

Terragrunt автоматически управляет зависимостями через блоки `dependency`. Например, секреты зависят от namespace, s3 и database, и получают их outputs.

## Использование

### Локальная разработка

1. Отредактируйте `infrastructure.yaml` для добавления/изменения ресурсов
2. Перейдите в директорию компонента:
```bash
cd live/stage/namespace
```

3. Инициализируйте Terragrunt:
```bash
terragrunt init
```

4. Просмотрите план:
```bash
terragrunt plan
```

5. Примените изменения:
```bash
terragrunt apply
```

### Развертывание всех компонентов

```bash
cd live/stage
terragrunt run-all apply
```

## Переменные окружения

- `YC_TOKEN` - токен Yandex Cloud
- `YC_CLOUD_ID` - ID облака
- `YC_FOLDER_ID` / `YC_STAGE_FOLDER_ID` - ID каталога
- `DOCKER_REGISTRY_USERNAME` / `DOCKER_REGISTRY_PASSWORD` - для секрета dockerhub
- `TF_STATE_BUCKET` - бакет для хранения state
- `TF_STATE_DYNAMODB_ENDPOINT` / `TF_STATE_DYNAMODB_TABLE` - для блокировок state

## GitLab CI

Проект использует динамическую генерацию GitLab CI пайплайнов через downstream pipelines. Для каждого компонента создаются джобы: validate, plan, apply.

## Принципы

1. **DRY** - вся конфигурация в одном файле `infrastructure.yaml`
2. **Универсальность** - модули не знают про конкретные сущности
3. **Декларативность** - описание желаемого состояния, а не шагов
4. **Идемпотентность** - повторный запуск безопасен
5. **Изоляция** - каждый компонент имеет свой state