Terraform

01Идея: инфраструктура как код

Infrastructure as code означает, что ваши серверы, сети и DNS описаны в текстовых файлах, хранятся в Git и меняются через pull request'ы, как код приложения. Terraform использует декларативный язык HCL: вы описываете желаемое конечное состояние (один сервер такого-то размера, одна DNS-запись, указывающая на него), а не шаги, как к нему прийти. Шаги Terraform вычисляет сам. Польза вполне конкретная. Staging-окружение может быть точной копией продакшена. Новый человек в команде читает код и понимает инфраструктуру. Изменения проходят ревью до того, как случатся, а история Git показывает, кто что изменил и зачем. Восстановление после аварии ускоряется, потому что инфраструктуру можно пересоздать из кода, хотя данные всё равно придётся брать из бэкапов.

• Декларативно: описываете что, а не как.
• Версионируется и проходит ревью, как код приложения.
• Terraform создаёт инфраструктуру; инструменты вроде Ansible настраивают то, что работает внутри серверов.

02Провайдеры и ресурсы

Сам Terraform ничего не знает об AWS или DigitalOcean. Провайдеры — это плагины, которые переводят ваш код в вызовы API одной платформы; есть провайдеры для AWS, Google Cloud, Azure, DigitalOcean, Hetzner, Cloudflare, GitHub, Kubernetes и сотен других сервисов. Вы объявляете нужные провайдеры и фиксируете их версии, затем terraform init скачивает их и записывает точные версии в lock-файл, который вы коммитите. Блок resource описывает один управляемый объект: сервер, бакет, DNS-запись. Блок data читает что-то уже существующее, не управляя им. Переменные делают код переиспользуемым, outputs выводят полезные значения вроде IP-адреса, а учётные данные берутся из переменных окружения, а не из кода.

1terraform {
2  required_version = ">= 1.10"
3  required_providers {
4    digitalocean = { source = "digitalocean/digitalocean", version = "~> 2.0" }
5    cloudflare   = { source = "cloudflare/cloudflare", version = "~> 5.0" }
6  }
7}
8 
9# tokens come from DIGITALOCEAN_TOKEN and CLOUDFLARE_API_TOKEN env vars
10provider "digitalocean" {}
11provider "cloudflare" {}
12 
13variable "ssh_key_fingerprint" { type = string }
14variable "cloudflare_zone_id" { type = string }

03Пример: сервер и его DNS-запись

Вот законченный маленький кусочек реальной инфраструктуры: сервер на Ubuntu и DNS-запись, указывающая на него хостнейм. Обратите внимание на ссылку digitalocean_droplet.web.ipv4_address внутри DNS-записи. Terraform читает такие ссылки, чтобы построить граф зависимостей: так он знает, что сервер должен существовать до создания записи, и может создавать независимые ресурсы параллельно. Если позже вы поменяете размер сервера, план покажет обновление на месте; если поменяете образ — покажет, что сервер нужно уничтожить и создать заново, и это ровно тот сюрприз, ради выявления которого план и существует. После apply output выведет новый IP.

1resource "digitalocean_droplet" "web" {
2  name     = "web-1"
3  image    = "ubuntu-24-04-x64"
4  region   = "fra1"
5  size     = "s-1vcpu-2gb"
6  ssh_keys = [var.ssh_key_fingerprint]
7}
8 
9resource "cloudflare_dns_record" "app" {
10  zone_id = var.cloudflare_zone_id
11  name    = "app.example.com"
12  type    = "A"
13  content = digitalocean_droplet.web.ipv4_address
14  ttl     = 1
15  proxied = true
16}
17 
18output "server_ip" { value = digitalocean_droplet.web.ipv4_address }

04Plan и apply

У повседневной работы чёткий ритм. terraform init готовит рабочую папку и скачивает провайдеры. terraform fmt и validate ловят проблемы со стилем и синтаксисом. terraform plan сравнивает три вещи: ваш код, state-файл и реальные ресурсы, — а затем печатает каждое действие со значком: плюс — создание, тильда — обновление на месте, минус — удаление, минус-плюс — замена. Внимательно читайте план, особенно любые удаления. Если сохранить план в файл и применить именно его, то выполнится ровно то, что вы проверили. В команде CI запускает plan на каждый pull request и публикует результат для ревью; apply запускается после мерджа из CI, а не с чьего-то ноутбука. Используйте prevent_destroy для ценных ресурсов вроде баз данных.

1terraform init
2terraform fmt -check
3terraform validate
4terraform plan -out=tfplan
5terraform apply tfplan
6 
7# inspect and troubleshoot
8terraform state list
9terraform output server_ip

05State, удалённый state и блокировки

Terraform хранит state-файл: соответствие между каждым ресурсом в коде и реальным объектом, которым он управляет, с его ID и атрибутами. Без state Terraform не может знать, что web в вашем коде — это сервер 12345 у провайдера. По умолчанию state — локальный файл, и это ломается, как только появляются два человека или CI-задача. Храните его удалённо — в бакете S3 или совместимом хранилище, в Terraform Cloud или другом backend'е — с включённым версионированием, чтобы можно было восстановиться после неудачной записи. Блокировка не даёт двум apply запуститься одновременно и испортить state. Backend S3 теперь поддерживает нативную блокировку через use_lockfile; старый способ с таблицей DynamoDB признан устаревшим. State может содержать секреты вроде паролей к базе, поэтому шифруйте его и ограничивайте доступ.

1terraform {
2  backend "s3" {
3    bucket       = "example-terraform-state"
4    key          = "prod/terraform.tfstate"
5    region       = "eu-central-1"
6    encrypt      = true
7    use_lockfile = true
8  }
9}

06Модули, дрифт и ландшафт инструментов

Модуль — это папка с кодом Terraform со входами и выходами, как функция. Напишите модуль веб-сервера один раз и вызывайте его для staging и продакшена с разными размерами. Держите модули маленькими и сфокусированными, фиксируйте версии общих модулей и храните окружения в отдельных state-файлах, чтобы ошибка в staging не могла задеть продакшен. Дрифт — это когда реальность перестала совпадать с кодом, обычно потому что кто-то поменял что-то руками в консоли. terraform plan его выявляет; дальше вы либо обновляете код, чтобы он совпадал, либо делаете apply, чтобы вернуть объявленное состояние. Что касается инструментов: в 2023 году HashiCorp перевела Terraform на Business Source License, а теперь сама входит в IBM. OpenTofu — open-source форк, в основном совместимый, с дополнениями вроде встроенного шифрования state. Pulumi использует TypeScript, Python или Go вместо HCL.

1module "web_staging" {
2  source = "./modules/web-server"
3  name   = "web-staging"
4  size   = "s-1vcpu-1gb"
5}
6 
7module "web_prod" {
8  source = "./modules/web-server"
9  name   = "web-prod"
10  size   = "s-2vcpu-4gb"
11}

07Как на самом деле работает plan: граф, неизвестные значения и порядок замены

Terraform превращает вашу конфигурацию в граф зависимостей. Каждый resource, data source, variable и output — это вершина, а каждая ссылка создаёт ребро. Во время plan он обновляет каждый управляемый ресурс у провайдера, сравнивает обновлённый state с конфигурацией и спрашивает провайдера, какое действие нужно. Значения, которые появляются только после создания, например IP нового сервера, отображаются как known after apply и передаются дальше как неизвестные, поэтому некоторые планы показывают целый каскад изменений. Terraform обходит граф параллельно, по умолчанию по десять операций одновременно, это настраивается через -parallelism. Когда аргумент нельзя обновить на месте, провайдер помечает его как forcing replacement, и по умолчанию Terraform сначала уничтожает старый объект, а потом создаёт новый. create_before_destroy меняет порядок на обратный, чтобы избежать даунтайма, — при условии, что имена не конфликтуют. Используйте depends_on только для скрытых зависимостей, которые не выражены ни одной ссылкой.

1resource "aws_launch_template" "web" {
2  name_prefix   = "web-"            # unique names allow create-before-destroy
3  image_id      = var.ami_id
4  instance_type = "t4g.small"
5 
6  lifecycle {
7    create_before_destroy = true
8    ignore_changes        = [tags["LastScannedAt"]]   # set by another tool
9  }
10}

08count против for_each и рефакторинг без уничтожения

count создаёт список экземпляров с адресацией по индексу: server[0], server[1], server[2]. Удалите средний элемент из входного списка — и все последующие индексы сдвинутся, поэтому Terraform запланирует уничтожить и пересоздать серверы, которые на самом деле не менялись. for_each создаёт map с адресацией по ключу, server["api"], server["worker"], так что удаление одного ключа затрагивает только этот экземпляр; предпочитайте его, когда у элементов есть естественная идентичность. Переименование ресурса или перенос в модуль тоже меняет его адрес, и без подсказки Terraform уничтожил бы старый адрес и создал новый. Блок moved объявляет переименование прямо в коде, поэтому план показывает перемещение без изменений, а коллеги и CI подхватывают его автоматически — terraform state mv так не умеет. Чтобы перестать управлять ресурсом, не уничтожая его, используйте блок removed с lifecycle destroy = false. Чтобы взять под управление существующий ресурс, используйте блок import.

1resource "digitalocean_droplet" "app" {
2  for_each = { api = "s-2vcpu-4gb", worker = "s-1vcpu-2gb" }
3  name     = "app-${each.key}"
4  size     = each.value
5  image    = "ubuntu-24-04-x64"
6  region   = "fra1"
7}
8 
9moved {
10  from = digitalocean_droplet.web
11  to   = digitalocean_droplet.app["api"]
12}
13 
14import {
15  to = cloudflare_dns_record.legacy
16  id = "zone_id/record_id"
17}

09Секреты: sensitive, ephemeral и write-only значения

Пометка переменной или output как sensitive = true лишь скрывает значение в выводе plan и в логах; в state-файл оно всё равно записывается открытым текстом. Именно поэтому state должен быть зашифрован, а доступ к нему — ограничен. Новые версии идут дальше. В Terraform 1.10 появились ephemeral input-переменные, outputs и ephemeral-ресурсы — значения, которые существуют во время запуска, но никогда не записываются в файлы plan или state, например пароль, полученный из secret manager. В Terraform 1.11 добавили write-only аргументы с суффиксом _wo, которые позволяют управляемым ресурсам принимать эти ephemeral-значения: провайдер отправляет секрет в API, но никогда его не сохраняет. Поскольку Terraform не видит сохранённое значение, для ротации вы увеличиваете сопутствующий аргумент version. Ещё более простой вариант, если платформа это поддерживает, — позволить сервису самому генерировать и хранить секрет, как RDS умеет с manage_master_user_password, и тогда Terraform его вообще не видит.

1ephemeral "random_password" "db" {
2  length = 32
3}
4 
5resource "aws_db_instance" "main" {
6  identifier          = "app-prod"
7  engine              = "postgres"
8  instance_class      = "db.t4g.medium"
9  allocated_storage   = 50
10  username            = "app"
11  password_wo         = ephemeral.random_password.db.result
12  password_wo_version = 1          # bump to rotate
13}

10Защитные барьеры: validation, check, тесты и policy as code

В Terraform есть несколько уровней встроенных проверок. Блоки validation у переменных отклоняют некорректный ввод ещё до планирования, например неизвестное имя окружения или размер инстанса не из разрешённого списка. Preconditions и postconditions внутри lifecycle ресурса фиксируют допущения, которые должны выполняться, например что выбранный образ собран под нужную архитектуру. Блоки check выполняют проверки после apply, например HTTP-запрос к новому endpoint, и выдают предупреждения, ничего не блокируя. Команда terraform test с файлами, оканчивающимися на .tftest.hcl, запускает plan или apply на тестовых входных данных и проверяет результаты — так авторы модулей ловят регрессии. За пределами самого Terraform tflint находит ошибки, специфичные для провайдеров, сканеры вроде Checkov или Trivy отмечают небезопасные настройки, например открытые security group, а policy-движки, такие как OPA с Conftest или Sentinel в HCP Terraform, применяют правила организации к плану до apply.

1variable "environment" {
2  type = string
3  validation {
4    condition     = contains(["staging", "prod"], var.environment)
5    error_message = "environment must be staging or prod."
6  }
7}
8 
9check "site_up" {
10  data "http" "health" { url = "https://app.example.com/healthz" }
11  assert {
12    condition     = data.http.health.status_code == 200
13    error_message = "Health check did not return 200."
14  }
15}