Быстрый старт

Это руководство поможет настроить TerraCi и сгенерировать первый пайплайн.

Установка

Homebrew (рекомендуется)

brew install edelwud/tap/terraci

Go

go install github.com/edelwud/terraci/cmd/terraci@latest

Docker

docker run --rm -v $(pwd):/workspace ghcr.io/edelwud/terraci:latest generate

Бинарник

Скачайте с GitHub Releases и добавьте в PATH.

Из исходников

git clone https://github.com/edelwud/terraci.git
cd terraci
make build
./terraci version

Быстрый старт

1. Инициализация конфигурации

Перейдите в корень вашего Terraform-проекта и выполните:

terraci init

Это создаст файл .terraci.yaml:

structure:
  pattern: "{service}/{environment}/{region}/{module}"
  min_depth: 4
  max_depth: 5
  allow_submodules: true

gitlab:
  terraform_binary: "terraform"
  image: "hashicorp/terraform:1.6"
  plan_enabled: true
  auto_approve: false

2. Валидация проекта

Проверьте, что TerraCi корректно обнаруживает модули:

terraci validate

Ожидаемый вывод:

✓ Found 12 modules
✓ Built dependency graph with 15 edges
✓ No circular dependencies detected
✓ 4 execution levels identified

Execution order:
  Level 0: vpc, iam
  Level 1: eks, rds, elasticache
  Level 2: app-backend, app-frontend
  Level 3: monitoring

3. Визуализация зависимостей (опционально)

Экспортируйте граф зависимостей:

terraci graph --format dot -o deps.dot
dot -Tpng deps.dot -o deps.png

4. Генерация пайплайна

Сгенерируйте GitLab CI пайплайн:

terraci generate -o .gitlab-ci.yml

5. Генерация только для изменённых модулей

Для инкрементальных деплоев:

terraci generate --changed-only --base-ref main -o .gitlab-ci.yml

CI окружения

TerraCi автоматически получает remote-ссылки при необходимости, поэтому --changed-only работает из коробки в GitLab CI даже с shallow clone.

Структура проекта

TerraCi ожидает следующую структуру директорий:

your-project/
├── .terraci.yaml          # Конфигурация TerraCi
├── service-a/
│   ├── production/
│   │   └── us-east-1/
│   │       ├── vpc/
│   │       │   └── main.tf
│   │       └── eks/
│   │           └── main.tf
│   └── staging/
│       └── us-east-1/
│           └── vpc/
│               └── main.tf
└── service-b/
    └── production/
        └── eu-west-1/
            └── rds/
                └── main.tf

Паттерн {service}/{environment}/{region}/{module} соответствует:

• service-a/production/us-east-1/vpc
• service-a/production/us-east-1/eks
• service-b/production/eu-west-1/rds

Определение зависимостей

TerraCi обнаруживает зависимости из data-источников terraform_remote_state:

# В eks/main.tf
data "terraform_remote_state" "vpc" {
  backend = "s3"
  config = {
    bucket = "my-terraform-state"
    key    = "service-a/production/us-east-1/vpc/terraform.tfstate"
    region = "us-east-1"
  }
}

resource "aws_eks_cluster" "main" {
  vpc_config {
    subnet_ids = data.terraform_remote_state.vpc.outputs.private_subnet_ids
  }
}

TerraCi парсит путь key и сопоставляет его с модулем vpc.

Следующие шаги

• Структура проекта — поддерживаемые структуры директорий
• Разрешение зависимостей — как определяются зависимости
• Справочник конфигурации — все опции конфигурации
• Справочник CLI — все доступные команды