devops-курс Все курсы

✻ Урок 7.3 · Тема 7: IaC: Terraform и Ansible

Terraform: remote state, модули, окружения

⏱ 3 ч

Как работать с кодом и когда идти дальше

Команды не нужно писать по памяти. Пользуйся примерами из урока и справкой. Ориентируйся на цель задания:

  • Запусти готовое. Код приложения и вспомогательных скриптов можно скопировать. Пойми, зачем они нужны, что запускают или меняют и как проверить результат. Разбирать каждую функцию внутри готового инструмента не требуется.
  • Измени по образцу. Разбери новые конструкции, объяснённые в уроке. Измени указанный параметр или часть кода, предскажи результат и проверь запуском.
  • Напиши сам. Собери свой вариант под условия задания. Образцы и справка разрешены: важно объяснить своё решение и проверить его работу.

Можно идти дальше, если ты выполнил практику, получил ожидаемый результат и понимаешь, что проверил. Если задание просит изменить код, проверь и своё изменение.

Непонятные детали готового инструмента можно оставить на потом. При ошибке запуска вернись к разбору вывода и типичным ошибкам в уроке.

Зачем это нужно

Аня и Борис ведут один проект «Заметок». У каждого state (файл состояния: список того, что Terraform уже создал, урок 7.1) лежит на своём ноутбуке. Аня запустила apply и создала ВМ. Борис про это не знает: его state пуст, и на тот же код он создаёт вторую ВМ. Через месяц счёт вырос вдвое, и никто не понимает почему. Если же оба запустят apply одновременно, они могут испортить сам файл состояния.

Когда state общий и с блокировкой, второй человек просто ждёт и видит такую строку:

Error: Error acquiring the state lock

Это значит «файл сейчас занят другим». Полное сообщение с именем владельца разберём в разделе про блокировку.

Вторая боль: код для dev и stage (dev это окружение для разработки и проб, stage это «репетиция» перед боевым), скопированный дважды, быстро расходится. В одном файле поправили, в другом забыли, и на «репетиции» всё работает, а на боевой системе нет.

Решений два. Первое: общий state в бакете (bucket: хранилище файлов в облаке, урок 6.2) с блокировкой, чтобы одновременно писал только один человек. Второе: модуль (module), то есть готовый «кирпич» кода: описал сеть и ВМ один раз, вызвал дважды. Это базовый уровень командной работы с Terraform, и про него спрашивают на собеседованиях.

Шаг проекта: state «Заметок» переезжает в бакет Object Storage (так Yandex Cloud называет хранилище файлов, аналог Amazon S3), сеть и ВМ выносятся в модуль infra/terraform/modules/notes-vm, а окружение dev вызывает этот модуль.

Что нужно знать

Картина целиком

Представь небольшую строительную фирму. Раньше у каждого прораба был свой личный журнал (local state). Теперь фирма завела общий журнал работ на проходной (remote state в бакете): любой прораб сначала читает журнал, потом работает. На журнале висит табличка «занято» (блокировка): пока один прораб делает записи, второй ждёт у двери. У журнала есть архив старых версий (версионирование бакета): если кто-то испортил страницу, её можно восстановить.

А чтобы каждая новая стройка не начиналась с нуля, у фирмы есть типовой проект (модуль): «дом с сетью, сервером и охраной». Для каждой площадки (dev, stage) берут один типовой проект, подставляют свои размеры и получают свой дом и свой журнал.

flowchart LR
    T["ты или CI<br>terraform в envs/dev"] -->|"1. блокировка"| L["notes/dev/terraform.tfstate.tflock<br>табличка «занято»"]
    T -->|"2. читает и пишет"| D["notes/dev/terraform.tfstate<br>журнал dev, старые версии хранятся"]
    T -.->|"у stage свой ключ"| ST["notes/stage/terraform.tfstate<br>журнал stage"]
    T -->|"вызывает"| M["modules/notes-vm<br>сеть, диск, группа, ВМ"]
    E1["envs/dev<br>свои значения"] --> M
    E2["envs/stage<br>свои значения"] --> M

Части схемы:

  • remote state и блокировка - общий журнал и табличка «занято»;
  • модуль - типовой проект, который вызывают из окружений;
  • окружение - каталог с вызовом модуля, своим backend и своим state;
  • import и moved - два способа сказать Terraform «этот объект уже существует» и «он просто переехал на другой адрес»;
  • зеркало провайдеров - обходной путь, если сайт, откуда Terraform качает плагины, недоступен.

Теория

Почему локальный state не подходит для команды

По умолчанию state (terraform.tfstate) лежит рядом с кодом, на твоём диске. Для одного человека и одного ноутбука это работает.

В уроке 7.1 мы выяснили: Terraform сравнивает три вещи (код, state, реальность) и без state не знает, какие объекты облака «его». У локального файла три слабых места:

  1. Файла нет у коллеги. Он клонирует репозиторий, запускает plan и видит «нужно создать всё». Если он применит, получатся дубликаты или ошибка «имя занято».
  2. В нём секреты. Terraform записывает атрибуты ресурсов открытым текстом, в том числе пароли и ключи (урок 7.2 показал это на пароле БД). Положить такой файл в git нельзя.
  3. Нет защиты от одновременной работы. Два apply одновременно читают одну версию state и пишут разные результаты, выигрывает тот, кто записал последним, а ресурсы первого «теряются».

Прикинь сам: Аня создала ВМ, а у Бориса нет её state. Что произойдёт, если Борис запустит apply с тем же кодом?

Terraform сверит код со своим пустым state и решит, что ВМ ещё нет. Получатся две ВМ или ошибка «имя занято»: Борис не знает о том, что уже сделала Аня.

Осторожно: «Закоммитим state в git, и у всех будет один файл». Не выйдет: секреты в истории git остаются навсегда, а сливать два разных state-файла через merge нельзя (это не текст для людей, а внутренний формат со счётчиком версий).

Главное: локальный state живёт у одного человека, хранит секреты и не защищён от двух одновременных apply. Всё остальное в уроке решает эти три слабости.

Проверь понимание: почему нельзя положить terraform.tfstate в git, даже если репозиторий приватный?

Ответ

Во-первых, в state значения ресурсов лежат открытым текстом, включая пароли и ключи, а круг людей с доступом к репозиторию шире, чем к секретам. Во-вторых, у git нет блокировки: два человека закоммитят разные версии, а слить state-файл merge’ем нельзя. В-третьих, история git навсегда сохранит секрет, даже если файл потом удалить.

Значит, state нужно вынести в общее место. Разберём, как это делает remote backend.

Remote backend: общий state в бакете

Нужно место без трёх слабостей выше: общее для всех, с правами доступа, с историей версий. Такое место называется удалённым хранилищем состояния (remote backend). Backend (бэкенд) это «драйвер хранения»: кусок Terraform, который знает, где и как читать и писать state. По умолчанию backend local: файл на диске.

Журнал один, лежит в известном месте, у входа проверяют пропуск. Если проходная закрыта (бакет недоступен), работать с Terraform нельзя вообще, поэтому бакет должен быть надёжным.

Для S3-совместимых хранилищ (Yandex Object Storage, AWS S3, MinIO) используется backend s3. Бакет (bucket) это хранилище объектов: объект это файл плюс его имя-ключ (key), например notes/dev/terraform.tfstate. Каталогов в бакете на самом деле нет: слэши в ключе это просто часть имени, а консоли рисуют из них «папки» для удобства. Порядок работы такой:

  1. Ты запускаешь terraform plan или apply.
  2. Terraform по настройкам backend идёт в бакет и скачивает объект-state.
  3. Считает план, при apply вносит изменения в облако.
  4. Записывает новую версию state обратно в бакет.

Сам Terraform ничего локально надолго не хранит: в каталоге .terraform/ лежит только запись о том, какой backend настроен. Поэтому после смены backend нужен terraform init.

Чтобы пустить Terraform в бакет, нужен ключ доступа. В S3-мире это пара: идентификатор ключа (access_key) и секрет (secret_key), как логин и пароль для программы. Terraform читает их из переменных окружения AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY, даже когда хранилище не Amazon (S3-протокол общий, поэтому названия унаследованы). Ключ выпускается для сервисного аккаунта (учётка для программы, урок 6.1) с правами только на этот бакет: утечка такого ключа не даст доступа ко всему облаку. Переменные окружения живут только в одном терминале: в новом их нужно выставить заново. Они понадобятся и в уроке 7.4, где terraform output читает state из этого бакета.

Пример: блок backend из задания 2, по строкам:

bucket = "notes-tfstate-ab12"        имя бакета, где лежит state (имя уникально на весь Object Storage)
key    = "notes/dev/terraform.tfstate"  имя объекта внутри бакета: путь «проект / окружение / файл»
region = "ru-central1"                  регион; для Yandex формальность, но S3-протокол его требует
endpoints = { s3 = "https://storage.yandexcloud.net" }   адрес «окошка» хранилища (у AWS не нужен)
use_lockfile = true                     блокировка файлом в том же бакете (следующий раздел)
skip_* = true                           отключить проверки, рассчитанные на Amazon (аккаунт, регионы)

Ключ notes/dev/terraform.tfstate выбран не случайно: у окружения stage будет notes/stage/terraform.tfstate, а бакет общий. Состояния разные, хотя бакет один.

Прикинь сам: Ты запускаешь plan на новом ноутбуке, где ещё нет ни одного файла state. Откуда Terraform узнает, что уже создано?

Из бакета: настройки backend лежат в коде, и Terraform сам скачает объект notes/dev/terraform.tfstate. Локальный state не нужен, нужен только init и ключ доступа к бакету.

Осторожно:

  • «Backend можно параметризовать переменными». Нет: блок backend читается раньше, чем Terraform вычисляет переменные, поэтому имя бакета и ключ пишутся в коде буквально или передаются при init флагом -backend-config.
  • «Бакет для state создаст сам Terraform». Можно, но state этого бакета придётся хранить где-то ещё: курица и яйцо. Поэтому бакет для state создают один раз руками (или отдельным маленьким проектом), как в задании 1.

Главное: remote backend это общий журнал состояния в бакете: у каждого окружения свой ключ, а доступ даёт сервисный аккаунт только на этот бакет.

Проверь понимание: в бакете лежит объект notes/dev/terraform.tfstate. Есть ли в бакете каталог notes?

Ответ

Нет. В объектном хранилище есть только объекты с именами. Слэши в имени это часть ключа, а «папки» рисует интерфейс для удобства. Поэтому «создать каталог» не нужно: достаточно записать объект с нужным именем.

Общий журнал не спасает от двух людей, которые пишут в него одновременно. Для этого нужна блокировка.

Блокировка: табличка «занято»

Даже в общем журнале два прораба могут одновременно вписать разные данные в одну страницу. Блокировка (state lock) гарантирует, что в каждый момент state изменяет только один процесс.

Блокировка это табличка «не беспокоить» на двери: вошёл, повесил, закончил, снял. Табличка не охранник: если процесс умер, она остаётся висеть, и её снимают вручную (force-unlock).

Перед операцией, которая может изменить state, Terraform создаёт запись о блокировке, а после завершения удаляет её. Способа два:

  • Старый: отдельная таблица в базе данных DynamoDB (в Yandex это YDB в режиме, совместимом с DynamoDB). Блокировка это строка в таблице. Минус: лишний ресурс, который тоже нужно создать и оплачивать.
  • Новый: параметр use_lockfile = true (появился в Terraform 1.10). Блокировка это маленький файл <ключ>.tflock рядом со state в том же бакете. Создаётся он «условной записью»: хранилище принимает объект только если такого ещё нет. Поэтому способ работает лишь там, где хранилище условную запись поддерживает. Для Yandex Object Storage не считай это очевидным, а проверь на своём бакете (задание 2). Запасной план, если проверка провалилась: запускать Terraform только из одного места с очередью (CI), а не с нескольких ноутбуков.

Схема работы:

sequenceDiagram
    participant A as Процесс A
    participant B as бакет
    participant C as Процесс B
    A->>B: создать .tflock
    B-->>A: ok, файла не было
    Note over A: работает, apply
    C->>B: создать .tflock
    B-->>C: отказ, файл уже есть (Error acquiring the state lock)
    A->>B: записать state
    A->>B: удалить .tflock

Помнишь строку Error acquiring the state lock из начала урока? Вот что идёт под ней целиком. Сообщение об ошибке из задания 2, поле за полем:

Lock Info:
  ID:        3d2c6a1e-...   уникальный номер блокировки, нужен для force-unlock
  Path:      ...            какой state заблокирован
  Operation: OperationTypeApply   что делает владелец: apply, plan и т. д.
  Who:       user@laptop    кто держит (пользователь и машина)

Читать это нужно как вопрос «кто и зачем?»: если Who живой человек или CI-задача, которая ещё идёт, ждёшь. Если процесс завершился аварийно (закрыли ноутбук, убили kill -9, оборвалась сеть), блокировка осталась «висеть». Тогда terraform force-unlock <ID> её снимает.

Прикинь сам: Ты запустил apply и закрыл ноутбук, блокировка осталась. Что получит коллега и что он сделает первым?

Ошибку Error acquiring the state lock с полями ID, Who, Operation. Сначала он выяснит по Who, жив ли процесс, и только потом снимет табличку через force-unlock <ID>. Флаг -lock=false не ставят: он отключает всю защиту.

Осторожно: блокировка берётся и на plan, не только на apply, поэтому параллельные запуски plan в CI могут мешать друг другу. Второе: force-unlock не чинит state, а только убирает табличку. Если убитый apply успел создать часть ресурсов, после разблокировки нужно прочитать plan: state мог остаться в промежуточном состоянии.

План на pull request. В командах plan часто запускает CI на каждый pull request (запрос на слияние кода), чтобы ревьюер читал план рядом с кодом. План можно сохранить (terraform plan -out=tfplan) и позже применить (terraform apply tfplan), но он привязан к тому state, с которым посчитан. Если за это время state кто-то изменил, Terraform откажет с Saved plan is stale, и план нужно посчитать заново. Поэтому «одобренный» план недельной давности применять нельзя.

Главное: блокировка не даёт двум процессам менять state одновременно; новый способ это файл .tflock рядом со state (use_lockfile = true), а force-unlock снимает только зависшую табличку.

Проверь понимание: ты запустил apply, закрыл крышку ноутбука, сеть пропала. Коллега получает Error acquiring the state lock. Что он делает первым?

Ответ

Смотрит поле Who и время, выясняет, жив ли процесс (пишет владельцу). Если владелец подтвердил, что запуск мёртв, или ответа нет и процесс явно завис, снимает блокировку terraform force-unlock <ID>, затем запускает plan и проверяет состояние. Сразу -lock=false не отключают: так теряется вся защита.

Блокировка защищает от гонки, но не от порчи данных. От порчи спасает версионирование бакета.

Версионирование бакета: кнопка «отменить»

State можно повредить: неудачная запись, ошибочное удаление, чужая команда state rm. Версионирование (versioning) бакета хранит все прошлые версии объекта, и испорченный файл можно откатить. Без него потеря state означает ручной импорт каждого ресурса.

Версионирование хранит прежние версии объекта, как история изменений в редакторе: случайно всё стёр, открыл предыдущую. Она занимает место и стоит денег, но state маленький, так что это копейки.

При включённом версионировании перезапись объекта создаёт новую версию, а старая остаётся с собственным идентификатором версии. «Удаление» тоже не стирает данные, а ставит метку удаления поверх. Восстановить значит скопировать нужную старую версию как текущую. Включать версионирование нужно заранее: задним числом прошлые версии не появятся.

Пример: в задании 1 вывод yc storage bucket get ... | jq '{name, versioning}' показывает "versioning": "VERSIONING_ENABLED". Это и есть проверка: если там VERSIONING_DISABLED, то после первой же аварии откатываться будет не к чему.

Прикинь сам: Версионирование включили в понедельник, state испортили во вторник. Можно ли откатиться? А если включить его в среду?

Во вторник испорченный state восстановить можно: старая версия лежит в бакете. Если включить версионирование в среду, откатиться не к чему: прошлые версии задним числом не появляются.

Осторожно: версионирование не заменяет блокировку: оно спасает от последствий, а блокировка предотвращает гонку.

Главное: версионирование включают заранее: оно хранит все прошлые версии state и не заменяет блокировку.

С общим state разобрались. Теперь займёмся кодом: как не копировать его для каждого окружения.

Соответствие AWS

Что делаем Yandex Cloud AWS
Бакет для state Object Storage S3
Блокировка (старый способ) YDB (Document API) DynamoDB
Ключи для backend статический ключ сервисного аккаунта IAM access key
Права на state роль на бакет IAM policy на бакет
Шифрование ключ Yandex KMS SSE-KMS
Провайдер yandex-cloud/yandex hashicorp/aws
Backend в коде backend "s3" с endpoints backend "s3"

Backend s3 один и тот же. Отличается адрес endpoint и несколько флагов, отключающих проверки, специфичные для AWS. (IAM это система прав в AWS, аналог ролей в Yandex; KMS это сервис хранения ключей шифрования.)

Модуль: типовой проект

В уроках 7.1 и 7.2 у тебя в каталоге лежат сеть, диск, группа безопасности и ВМ. Когда понадобится stage, первая мысль: скопировать файлы. Копия начинает жить отдельно: в одну добавили правило, в другую забыли. Модуль (module) даёт одно описание, которое вызывают несколько раз с разными значениями.

Модуль похож на функцию: код один, а значения задают при вызове. Отличие в том, что «возвращаемого значения» у него нет: наружу он отдаёт только то, что явно объявлено в output.

Модуль это обычный каталог с .tf файлами. Тот каталог, из которого ты запускаешь terraform, называется корневым модулем (root module), у нас это envs/dev. Из него блоком module вызывают дочерний модуль (child module):

flowchart TD
    R["envs/dev: корневой модуль<br>main.tf, backend.tf, moved.tf<br>здесь запускаешь terraform"] -->|"входы: my_ip_cidr, vm_cores"| C["modules/notes-vm: дочерний модуль<br>variables.tf, network.tf, vm.tf, outputs.tf"]
    C -->|"выход: public_ip"| O["module.notes_vm.public_ip<br>в envs/dev"]

Правила, которые спасают на практике:

  • Модуль знает только то, что ему передали. Значения идут через variable. Он не читает переменные вызывающего и не берёт чужой state.
  • Наружу выдаёт только output. Можно module.notes_vm.public_ip, нельзя module.notes_vm.yandex_compute_instance.notes.
  • Провайдера настраивают в корневом модуле, а не в дочернем: у нас versions.tf и providers.tf остаются в envs/dev, модуль их использует.
  • Выносить стоит то, что повторяется хотя бы дважды и меняется вместе. Модуль на один ресурс без логики это лишний слой.

Версию модуля фиксируют. У локального source (путь на диске) версии нет, поэтому правка модуля сразу видна всем окружениям, которые его вызывают. Для модуля из git пишут source = "git::https://.../notes-vm.git?ref=v1.2.0" (тег), для реестра Terraform version = "~> 1.2" (разбор такого ограничения был в уроке 7.1).

Пример: в модуле notes-vm объявлена переменная vm_cores со значением по умолчанию 2. Вызов:

module "notes_vm" {
  source   = "../../modules/notes-vm"   # путь от корневого модуля до каталога модуля
  vm_cores = 2                          # значение для variable "vm_cores" внутри модуля
}

Внутри модуля в ресурсе написано cores = var.vm_cores, и Terraform подставит 2. Если из envs/stage вызвать тот же модуль с vm_cores = 4, получится ВМ побольше, а код один. Terraform при init нужно «установить» модуль: для локального пути это просто запоминание ссылки, для git-модуля ещё и скачивание. Поэтому после добавления блока module нужен terraform init (иначе Error: Module not installed).

Прикинь сам: В модуле notes-vm у vm_cores значение по умолчанию 2. Из envs/stage вызвали его с vm_cores = 4. Сколько ядер у ВМ в stage и в dev?

В stage 4, в dev 2 (если там значение не задано). Код один, значения свои у каждого вызова.

Осторожно:

  • Модуль и окружение это не одно и то же. Модуль это «как устроено», окружение это «с какими значениями и в каком state».
  • «Вынес в модуль, значит, стало чище». Если модуль вызывают один раз и внутри нет логики, прибыли нет.

Главное: модуль это каталог с .tf файлами, который вызывают блоком module; он знает только то, что ему передали, и отдаёт наружу только output.

Проверь понимание: внутри модуля нужно знать my_ip_cidr (адрес, с которого разрешён SSH). Где его объявить и как передать?

Ответ

Объявить variable "my_ip_cidr" внутри модуля (это вход модуля) и передать значением в блоке module в корневом модуле: my_ip_cidr = var.my_ip_cidr. Сам корневой модуль, в свою очередь, тоже объявляет variable "my_ip_cidr" и получает значение из terraform.tfvars. Модуль сам «наружу за переменной» не ходит.

Если перенести ресурсы в модуль, их адреса поменяются. Что при этом будет с state, разберём дальше.

Адрес ресурса и блок moved

Это самое частое место, где новички ломают инфраструктуру при рефакторинге. Terraform находит ресурс в state по его адресу. Если адрес изменился, старый ресурс для него «исчез», а новый «появился».

Вот одна и та же ВМ до и после переноса в модуль:

до:     yandex_compute_instance.notes
после:  module.notes_vm.yandex_compute_instance.notes

Для Terraform это два разных ресурса. Старого адреса в коде больше нет (значит, ресурс нужно удалить), нового адреса в state нет (значит, нужно создать). Для сети или ВМ это «удалить и создать заново», то есть потеря машины и её данных. Так же, как в почте: если дом перенумеровали, почтальон по старому номеру не найдёт жильцов; запись «дом 5 теперь дом 7» говорит, что жильцы те же, и такая запись называется moved.

Адрес читается слева направо, как путь к файлу. Три примера:

  • yandex_compute_instance.notes: простой ресурс в корневом модуле. Читается так: «тип ресурса, точка, его имя в коде».
  • module.notes_vm.yandex_compute_instance.notes: тот же ресурс внутри модуля. Читается так: «в вызове модуля notes_vm лежит ресурс такого типа и имени».
  • yandex_vpc_security_group_rule.ingress["ssh"]: ресурс с for_each. Читается так: «из копий правила ingress та, что с ключом ssh». Копию (экземпляр, instance) for_each создаёт по одной на каждый ключ, как три правила группы безопасности из урока 7.2.

Блок moved { from = ..., to = ... } сообщает Terraform: это один и тот же объект. Блок пишут в корневом модуле, потому что он отвечает за то, как выглядит состояние его дерева. Команда terraform state mv делает то же самое императивно, прямо в state, но без следа в коде, поэтому в команде предпочитают moved.

Что покажет plan после переноса файла vm.tf в модуль и вызова module "notes_vm":

  • Без moved: plan покажет yandex_compute_instance.notes will be destroyed и module.notes_vm.yandex_compute_instance.notes will be created, итог Plan: N to add, 0 to change, N to destroy.
  • С moved: plan пишет yandex_compute_instance.notes has moved to module.notes_vm.yandex_compute_instance.notes, итог 0 to add, 0 to change, 0 to destroy.

Для ресурсов с for_each (у нас yandex_vpc_security_group_rule.ingress) блок moved пишется на весь ресурс одним блоком: Terraform сам сопоставит экземпляры ["ssh"], ["http"], ["https"].

Прикинь сам: Ты перенёс ВМ в модуль и запустил plan без блока moved. Какой будет итоговая строка плана?

Что-то вроде Plan: N to add, 0 to change, N to destroy: старый адрес исчез из кода (удалить), новый не найден в state (создать). Для ВМ это потеря машины и данных.

Осторожно: блок moved не нужно удалять сразу после apply: если у коллеги или в другом окружении state ещё со старыми адресами, блок им тоже нужен. Обычно его оставляют на несколько релизов.

Главное: Terraform ищет ресурс в state по адресу; смена адреса выглядит как «удалить и создать», а блок moved объясняет, что объект тот же.

Проверь понимание: ты переименовал ресурс внутри модуля с notes на main. Что покажет plan и как исправить?

Ответ

Адрес поменялся, поэтому Terraform предложит удалить старый и создать новый (для ВМ это потеря машины). Исправление: блок moved { from = module.notes_vm.yandex_compute_instance.notes to = module.notes_vm.yandex_compute_instance.main }. Он сообщает, что ресурс тот же и просто сменил адрес.

Один код, много окружений: теперь решим, как их разделять, каталогами или workspaces.

Окружения: каталоги или workspaces

Окружение это полный независимый набор инфраструктуры (dev для проб, stage для репетиции, prod для настоящей работы). Нужно, чтобы эксперимент в dev не мог случайно изменить prod.

Каталоги это три отдельные комнаты с табличками на дверях, в каждой свой журнал. Workspaces это один каталог и три журнала на одной полке, и в какой пишешь, ты помнишь сам: ошибиться полкой проще.

Есть два подхода:

  • Каталоги: envs/dev/, envs/stage/. У каждого свой backend.tf с отдельным key и свой state, общий код лежит в модулях. Многословно, зато на экране видно, где ты (по пути в терминале), и права на state можно разделить: dev открыт всем, prod только CI.
  • Workspaces (рабочие пространства): один код и много state в одном backend, переключение командой terraform workspace select stage. Текущий workspace нигде в коде не виден, права на бакет общие.
flowchart LR
    subgraph K["Каталоги: видно по пути, где ты"]
        K1["envs/dev"] --> KS1["key = notes/dev/..."]
        K2["envs/stage"] --> KS2["key = notes/stage/..."]
    end
    subgraph W["Workspaces: видно только по workspace show"]
        W0["один каталог"] --> W1["workspace dev: env:/dev/..."]
        W0 --> W2["workspace stage: env:/stage/..."]
    end

Пример: ты в envs/stage и случайно запустил terraform destroy. Худшее, что произойдёт: удалится stage. Тот же промах в workspace prod без проверки terraform workspace show удалит prod, потому что каталог и код те же самые.

Прикинь сам: Ты случайно запустил terraform destroy. В каком случае пострадает prod: если ты в каталоге envs/stage или в workspace prod?

В workspace prod: код и каталог те же, текущий workspace нигде не виден. В envs/stage удалился бы только stage, и это видно по пути в терминале.

Осторожно: «Workspaces это то же самое, что окружения». Workspace это только отдельный state. Различия в размерах, именах и адресах придётся задавать условиями в коде, и он быстро усложняется. Команды чаще выбирают каталоги, а workspaces оставляют для одинаковых временных копий (например, окружение на время ревью). В курсе идём через каталоги.

Главное: каталоги дают явное разделение (свой backend и свои права), workspaces дают только отдельный state; в курсе идём через каталоги.

Проверь понимание: зачем у dev и stage разные key в backend, если бакет один?

Ответ

Если ключ одинаковый, оба окружения будут читать и перезаписывать один и тот же state и «увидят» ресурсы друг друга: apply в stage начнёт менять или удалять ресурсы dev. Разные ключи дают разные независимые state в одном бакете.

У окружений есть общий риск: в state лежат секреты. Посмотрим, как их защитить.

Секреты и права вокруг state

Мы перенесли state в общий бакет, значит, теперь в нём лежат секреты для всех, у кого есть доступ к бакету. Удобство общего хранилища означает и общий риск: один неверно выданный доступ открывает пароли и ключи, которые Terraform записал в state.

Общий журнал на проходной, в котором, кроме списка окон, записаны коды от сейфов. Любой, кто может читать журнал, может и открыть сейфы. Поэтому журнал держат в закрытой комнате, а не на общем столе.

Защита state строится из четырёх слоёв:

  1. Права на бакет. Читать и писать state может только сервисный аккаунт Terraform и небольшая группа людей (урок 6.1: чем уже права, тем дешевле ошибка). Публичный доступ к бакету выключен.
  2. Шифрование. Хранилище шифрует объекты «на диске» (ключ управляется облачным сервисом KMS, строка в таблице соответствия AWS выше). Это защита от утечки самих дисков провайдера, но не от человека с правом чтения бакета.
  3. Версионирование. Старые версии state тоже содержат старые секреты, поэтому права на них те же.
  4. Минимум секретов в самом state. Всё, что Terraform прочитал или подставил в ресурс (например, в metadata.user-data), попадает в state. Надёжнее передавать ВМ ссылку на секрет, а сам пароль получать на ВМ из хранилища секретов (тема 9). Пока мы передаём пароль через TF_VAR_notes_db_password (урок 7.2), он окажется в state.

Пример: проверка «открывается ли state без ключа». Без AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY любое обращение к бакету (terraform plan, yc storage s3api list-objects с пустым профилем) должно закончиться ошибкой доступа, а не содержимым файла. Если содержимое читается анонимно, бакет открыт всему интернету, и секреты из state считай утёкшими.

Прикинь сам: Бакет зашифрован на стороне хранилища. Может ли человек с правом чтения бакета увидеть пароль из state?

Может: хранилище расшифровывает объект для любого, кто имеет право чтения. Шифрование защищает диски провайдера, а не доступ.

Осторожно: проверить, что бакет закрыт, надо самому, а не по ощущению. Пока не выполнена проверка из задания 1 (публичный доступ выключен, версионирование и шифрование включены), считай, что state открыт.

Главное: state с секретами защищают правами на бакет, отдельным узким ключом, закрытым публичным доступом и минимумом секретов внутри.

Проверь понимание: ты выдал сервисному аккаунту Terraform роль на весь каталог «чтобы точно работало». Что плохого, если его ключ утечёт?

Ответ

Злоумышленник получит доступ не только к бакету со state, но и ко всему каталогу: сможет создавать и удалять ВМ, читать данные, запускать платные ресурсы. Ключ для backend должен открывать только один бакет: тогда ущерб ограничен чтением state, а это уже повод сменить секреты в нём, но не потеря всего облака.

Бывает, что backend приходится менять. Как не потерять state при переезде, разберём дальше.

Смена backend: migrate-state и reconfigure

Backend не вечен: бакет переименовали, окружение разделили, key поправили. Terraform помнит, какой backend использовал в прошлый раз, и при несовпадении не гадает, куда ты хотел писать state. Иначе он мог бы молча начать работу с пустым state и предложить создать всё заново.

Переезд в другой офис. Перевезти архив со старого места (-migrate-state) или начать с пустых шкафов в новом (-reconfigure): решение нужно принять явно, оба варианта законны, но имеют разные последствия.

После init Terraform сохраняет настройки backend в .terraform/terraform.tfstate (служебный файл, не путай со state). Перед каждой операцией он сравнивает запись с backend.tf. Если они различаются, plan останавливается с Error: Backend initialization required (причина Backend configuration block has changed), а terraform init без флагов пишет Error: Backend configuration changed. В обоих случаях нужно запустить init с одним из флагов:

  • terraform init -migrate-state: скопировать state из старого места в новое. Если в новом месте уже что-то лежит, спросит, перезаписывать ли.
  • terraform init -reconfigure: просто переключиться на новый backend, ничего не копируя и забыв прежние настройки. Годится, когда state уже перенесён руками или не нужен.

Пример: ты поменял в backend.tf key с notes/dev/terraform.tfstate на notes/dev2/terraform.tfstate. С -reconfigure Terraform пойдёт в новое место, найдёт там пустоту и решит, что ничего не создавал: plan предложит создать всё заново. С -migrate-state он сначала скопирует state в notes/dev2/..., и plan покажет No changes. Поэтому «не помогло, добавлю -reconfigure» не универсальный совет.

Прикинь сам: Ты поменял key в backend.tf и запустил init -reconfigure. Что покажет plan?

Предложит создать всё заново: по новому ключу state пуст, а -reconfigure ничего не копирует. Нужен был -migrate-state.

Осторожно: rm -rf .terraform как лекарство от этой ошибки. Каталог удалится, init пройдёт, но state при этом не скопирован: получится то же, что -reconfigure.

Главное: -migrate-state копирует state на новое место, -reconfigure просто переключает backend; выбирай осознанно.

Проверь понимание: в каком случае безопасен -reconfigure?

Ответ

Когда state в новом месте уже лежит (его перенесли руками или по смыслу это тот же объект, например сменился только способ подключения к тому же бакету). Если нужный state остался только в старом месте, -reconfigure даст пустую картину, и правильный флаг -migrate-state.

Иногда state приходится править напрямую. Для этого есть команды terraform state.

Ручные операции над state

Иногда state нужно поправить без изменения инфраструктуры: переименовать адрес, убрать ресурс из-под управления Terraform, посмотреть атрибуты. Для этого есть команды семейства terraform state.

Это правка записей в журнале без изменений в облаке: вещи остаются на месте, меняется только запись о них.

Основные команды:

  • terraform state list печатает адреса всех ресурсов (мы делали это в задании 2);
  • terraform state show <адрес> показывает атрибуты одного ресурса (осторожно: там могут быть секреты);
  • terraform state mv <откуда> <куда> меняет адрес (то же, что блок moved, но сразу и без следа в коде);
  • terraform state rm <адрес> убирает ресурс из state: объект в облаке остаётся жить, но Terraform о нём «забывает»;
  • terraform state pull печатает весь state (мы использовали его для страховки).

Любая запись в state идёт под блокировкой, а каждая запись это новая версия объекта в бакете: откат возможен.

Пример: нужно временно вывести диск из-под Terraform, не удаляя его. terraform state rm yandex_compute_disk.data удалит запись. Следующий plan увидит в коде ресурс yandex_compute_disk.data, а в state его нет, и предложит создать диск заново. Значит, state rm нужно сочетать с удалением блока из кода (или блоком removed в новых версиях).

Прикинь сам: Ты выполнил terraform state rm yandex_compute_disk.data, а блок диска остался в коде. Что покажет следующий plan?

Предложит создать диск заново: в коде он есть, в state его нет. Сам диск в облаке не удалён и продолжает стоить денег.

Осторожно: «state rm удаляет ресурс». Он удаляет только запись, а сам объект в облаке продолжает работать и стоить денег. Для удаления самого ресурса нужен destroy (или убрать блок из кода и применить).

Главное: state rm удаляет только запись, state mv меняет адрес без следа в коде, а moved делает то же самое, но виден в Git.

Проверь понимание: чем terraform state mv отличается от блока moved?

Ответ

Результат тот же: ресурс сохраняется под новым адресом без пересоздания. Но state mv правит state немедленно и вручную, и в репозитории не остаётся следа, поэтому коллеги со своими копиями кода и state могут не узнать о переносе. Блок moved лежит в коде, попадает в git и применяется при обычном plan/apply в любом окружении.

А если запись о ресурсе потеряна совсем, а сам ресурс жив, пригодится импорт.

Import и потеря state

Terraform управляет только тем, что записано в его state. Ресурс, созданный руками в консоли, или весь объект после потери state для него не существует: apply попытается создать дубликат и упадёт на конфликте имён. Нужен способ сказать «вот этот объект облака соответствует этому блоку кода».

Если объект есть в облаке, но в журнале его нет, Terraform не знает, что он существует. Импорт это запись в журнал: «вот этот объект числится как блок X».

Два пути восстановления:

  1. Восстановить state из версии бакета (версионирование включают заранее). Самый быстрый способ: скопировать предыдущую версию объекта как текущую.
  2. Привязать существующие ресурсы заново. Старая форма: terraform import <адрес> <id>. С Terraform 1.5 можно записать блок import в коде, и привязка произойдёт при обычном apply:
import {
  to = module.notes_vm.yandex_vpc_network.notes   # адрес в коде
  id = "enp7example0000000000"                    # идентификатор объекта в облаке
}

Идентификатор берут из облака: yc vpc network list и аналогичные команды. Важно: импорт не пишет код. Он записывает в state реальные значения объекта, а описание ресурса в .tf ты создаёшь сам (с Terraform 1.5 есть помощник terraform plan -generate-config-out=файл.tf, который набрасывает заготовку, но её всё равно нужно проверять глазами; работает для блока import в корневом модуле, для ресурса внутри модуля код переноси вручную).

Пример: ты импортировал сеть и запустил plan. Возможны два исхода:

  • No changes. Your infrastructure matches the configuration. - код совпадает с реальностью, работа закончена;
  • ~ update in-place с перечнем атрибутов - код отличается от реального объекта (например, в коде нет описания, а в облаке оно есть). Правишь код, пока не получишь No changes, либо осознанно применяешь, чтобы привести объект к коду.

Прикинь сам: После terraform import команда plan показывает ~ update in-place. Что это значит и что делать?

Код не совпадает с настоящим ресурсом: импорт записал в state реальные значения, а описание в .tf другое. Правь код, пока не получишь No changes.

Осторожно: «Import создаст ресурс». Нет, он не создаёт и не меняет ничего в облаке, только пишет строку в state. Второе: после потери state нельзя запускать apply «на пустом»: он создаст дубликаты. Сначала восстановление или импорт, затем plan.

Главное: import только пишет строку в state и ничего не создаёт и не пишет в код; после потери state сначала восстанавливают или импортируют, потом делают plan.

Проверь понимание: после terraform import команда plan показывает изменения. Что это значит?

Ответ

Код не совпадает с реальным ресурсом: импорт положил в state настоящие значения, а в коде другие. Правь код, пока plan не покажет No changes, либо осознанно применяй, если ресурс нужно привести к коду.

Остался вопрос воспроизводимости: откуда берутся провайдеры и как закрепить их версии.

Lock-файл, каталог .terraform и зеркало провайдеров

Провайдер (плагин, который умеет работать с API облака, урок 7.1) Terraform скачивает из интернета. Это создаёт две проблемы: версия через месяц может стать другой и сломать код, а сайт registry.terraform.io может быть недоступен (из России доступ к нему нестабилен).

Lock-файл это точный список «какой бренд, какой вес, контрольная пломба» (чтобы через месяц купить то же самое). Зеркало это второй магазин, где те же товары, когда первый закрыт.

Как это устроено:

  • .terraform.lock.hcl появляется после terraform init: записывает точную версию каждого провайдера и хеши (контрольные суммы) пакетов. При следующих init Terraform берёт именно эти версии и проверяет хеши, поэтому зеркало не сможет подложить другую сборку. Файл коммитят. Обновить версии осознанно: terraform init -upgrade.
  • .terraform/ это кэш: скачанные бинарники провайдеров и запись о настроенном backend. Собирается заново командой init, в git не нужен.
  • Зеркало провайдеров (provider mirror) это сервер с копией пакетов. Настраивается в файле ~/.terraformrc (он относится к твоему пользователю, а не к проекту) блоком provider_installation: network_mirror говорит, откуда качать провайдеры, а direct перечисляет то, что качается напрямую. Адрес зеркала меняется, поэтому в примере он помечен: проверь актуальный адрес в документации Yandex Cloud по Terraform. Зеркало должно отдавать все нужные провайдеры, а если прямая загрузка из твоей сети не работает, есть запасной filesystem_mirror (каталог с заранее скачанными архивами).
flowchart TD
    I["terraform init"] --> A[".terraform.lock.hcl<br>какая версия и какие хеши"]
    I --> B["~/.terraformrc<br>откуда качать: зеркало или registry"]
    A --> D["качает провайдер, сверяет хеш"]
    B --> D
    D --> E["кладёт в .terraform/providers/"]

Пример: без lock-файла через месяц init поставит провайдер новее, чем у коллеги, и один из вас увидит в плане лишние изменения. С lock-файлом оба получат 0.232.0. Если lock-файл составлен на macOS, а CI работает на Linux, в нём могут не оказаться хеши для Linux: тогда помогает terraform providers lock -platform=linux_amd64 -platform=darwin_arm64, который записывает хеши для нескольких платформ сразу.

Прикинь сам: Коллега закоммитил .terraform.lock.hcl, ты нет. Через месяц у вас разные версии провайдера. Почему?

Без lock-файла init берёт самую свежую версию в рамках ограничения из versions.tf, а у коллеги версия закреплена. План у вас покажет разные изменения.

Осторожно: lock-файл не добавляют в .gitignore «потому что мешает»: он как раз и даёт воспроизводимость. Обратное тоже ошибка: коммитить .terraform/ (сотни мегабайт бинарников, которые и так скачаются).

Главное: lock-файл закрепляет версии и хеши провайдеров и лежит в Git; .terraform/ это кэш, его не коммитят; зеркало нужно, когда registry недоступен.

Проверь понимание: что произойдёт, если удалить .terraform.lock.hcl и запустить init через месяц?

Ответ

Terraform выберет самую новую версию провайдера, подходящую под ограничение в versions.tf (например, ~> 0.232 допускает все 0.x от 0.232 и выше), и напишет новый lock-файл. Версия может оказаться другой, чем у коллег и в CI, и plan покажет неожиданные изменения. Lock-файл нужен именно для того, чтобы версии не «плавали».

Соберём всё вместе: что происходит при одном plan в окружении с модулем и remote state.

Сквозной разбор: что происходит при plan с модулем и remote state

Соберём всё из урока в один запуск, чтобы части встали на места. Ты в envs/dev и выполняешь terraform plan.

1. init уже сделан: известен backend (бакет + ключ) и модуль ../../modules/notes-vm
2. plan берёт блокировку: создаёт notes/dev/terraform.tfstate.tflock в бакете
3. скачивает state: notes/dev/terraform.tfstate
4. применяет moved: если в state старые адреса, а в moved.tf есть блок, то
   в плане они отображаются как «has moved to ...»
5. раскрывает module "notes_vm": подставляет значения в variable модуля
   (my_ip_cidr, notes_db_password) и вычисляет ресурсы с адресами
   module.notes_vm.<тип>.<имя>
6. refresh: спрашивает API облака, как выглядит каждый ресурс сейчас
7. сравнивает код, state и облако, печатает план
8. снимает блокировку

Если на шаге 2 получена ошибка блокировки, дальше Terraform не идёт. Если на шаге 4 нет блока moved, на шаге 7 ты увидишь пары destroy и create. Если на шаге 5 не хватает значения переменной, план остановится с Missing required argument до обращения к облаку. Умение назвать шаг, на котором сломалось, это и есть диагностика.

Прикинь сам: На каком шаге plan остановится, если в модуль не передано значение обязательной переменной, и дойдёт ли он до облака?

На шаге 5, когда раскрывается модуль: будет Missing required argument. До обращения к облаку (шаг 6) дело не дойдёт.

Главное: умение назвать шаг, на котором сломался plan, и есть диагностика: блокировка, state, moved, модуль, refresh, сравнение.

Практика

Работаем в ~/notes/infra/terraform. Файлы versions.tf, providers.tf, network.tf, variables.tf, vm.tf, cloud-init.yaml.tftpl, outputs.tf и рабочий terraform.tfvars уже есть из уроков 7.1 и 7.2, а ресурсы из них созданы в облаке (сеть notes, подсеть notes, диск notes-data, группа notes-sg, ВМ notes-vm). Нужны Terraform, yc с настроенным профилем (урок 6.1), jq (программа для разбора JSON, урок 1.2) и SSH-ключ из урока 6.2. Если ты удалил ресурсы через terraform destroy после 7.2, сначала повтори apply из 7.2: нам нужно, чтобы в state было что переносить.

Трек без облака: вместо Object Storage поднимается MinIO (бесплатное S3-совместимое хранилище) в контейнере (версия не закреплена, проверь актуальный образ). Backend настраивается так же, меняется только endpoints.s3.

Задание 1. Бакет и ключ для state

Цель: создать бакет с версионированием и отдельный ключ, которым Terraform будет ходить в него.

Предскажи: можно ли создать бакет для state тем же Terraform, который потом будет в нём хранить state?

Ответ

Нет. Чтобы создать бакет, Terraform записал бы его в state, а state должен лежать в этом самом бакете, которого ещё нет: курица и яйцо. Поэтому бакет для state создают один раз вручную.

Шаги:

  1. Создай бакет. export кладёт значение в переменную окружения этого терминала, чтобы не набирать имя снова. yc storage bucket create --name ... просит облако создать бакет с таким именем. Имя уникально на весь Object Storage, поэтому замени CHANGE_ME своим суффиксом (например, инициалами и числом). В имени допустимы только строчные латинские буквы, цифры и дефис:
export TF_BUCKET="notes-tfstate-CHANGE_ME"   # вместо CHANGE_ME свой суффикс
yc storage bucket create --name "$TF_BUCKET"
  1. Включи версионирование: оно хранит прошлые версии объектов, и при порче state есть путь назад.
yc storage bucket update --name "$TF_BUCKET" --versioning versioning-enabled
  1. Создай сервисный аккаунт для state. Это отдельная «учётка для программы», чтобы ключ Terraform открывал только бакет, а не всё облако:
yc iam service-account create --name notes-tf-state

Выдай ему права на бакет, а не на весь каталог. Флаг --grants задаёт разрешения на бакет, grantee-id это идентификатор аккаунта (поле id из yc iam service-account get). Точный синтаксис сверь с yc storage bucket update --help: он может меняться между версиями yc. Более грубая альтернатива: роль storage.editor на каталог, как в уроке 6.2 (проще, но шире, чем права на один бакет).

SA_ID="$(yc iam service-account get notes-tf-state --format json | jq -r .id)"
yc storage bucket update --name "$TF_BUCKET" \
  --grants "grant-type=grant-type-account,grantee-id=$SA_ID,permission=permission-full-control"

Разбор: $(...) подставляет вывод внутренней команды, jq -r .id достаёт поле id из JSON (-r убирает кавычки), обратный слэш \ в конце строки означает «команда продолжается на следующей».

  1. Выпусти статический ключ доступа и передай его окружению. Значения не печатай и не коммить. > перенаправляет вывод команды в файл. umask 077 в скобках делает так, что файл с самого начала создаётся с правами только для тебя (600, урок 1.3), а не открывается на мгновение для всех; ls -l покажет -rw-------:
(umask 077; yc iam access-key create --service-account-name notes-tf-state --format json > ~/.notes-tf-key.json)
ls -l ~/.notes-tf-key.json
export AWS_ACCESS_KEY_ID="$(jq -r .access_key.key_id ~/.notes-tf-key.json)"
export AWS_SECRET_ACCESS_KEY="$(jq -r .secret ~/.notes-tf-key.json)"

Имена AWS_* это историческое наследие: backend s3 читает ключи из них, даже когда хранилище не Amazon. Эти переменные живут в одном терминале: в новом выставь их снова теми же двумя командами export.

  1. Проверь, что бакет закрыт. Полное описание бакета покажет флаг --full (точные поля сверь с yc storage bucket get --help): в блоке публичного доступа (anonymous_access_flags) чтение и список должны быть выключены, а если включено шифрование, оно видно в описании. Выключен публичный доступ или нет, надо проверить, а не предполагать:
yc storage bucket get --name "$TF_BUCKET" --full --format json | jq '{name, versioning, anonymous_access_flags, encryption}'

Если поле encryption пустое, шифрование на стороне хранилища не включено: включи его по документации Yandex Cloud или осознанно прими риск для учебного бакета.

Что должно получиться:

yc storage bucket get --name "$TF_BUCKET" --format json | jq '{name, versioning}'
{
  "name": "notes-tfstate-ab12",
  "versioning": "VERSIONING_ENABLED"
}

ИИ: если yc выдал непонятную ошибку про права или имя бакета, вставь текст ошибки нейросети (без ключей): она подскажет, чего не хватает, но имена команд yc сверяй с yc storage --help.

Как читать вывод: name это имя твоего бакета. versioning должен быть VERSIONING_ENABLED. Если там VERSIONING_DISABLED, шаг 2 не сработал, и откатывать испорченный state будет не к чему. Полей у yc больше, мы выбрали два через jq '{name, versioning}'.

Объясни себе:

  1. Почему права выдаются на бакет, а не на весь каталог?
  2. Чем утечка этого ключа опаснее утечки одного terraform.tfstate без ключей?

Типичные ошибки:

  • ERROR: rpc error: code = AlreadyExists desc = Bucket already exists: имя занято кем-то другим. Добавь уникальный суффикс.
  • jq: command not found: не установлен jq. Поставь sudo apt install jq (Ubuntu) или brew install jq (macOS).
  • Ключ попал в git: считай его скомпрометированным, отзови (yc iam access-key delete) и выпусти новый.

Задание 2. Миграция state в бакет и проверка блокировки

Цель: перенести локальный state в бакет и убедиться, что второй параллельный запуск не пройдёт.

Предскажи: если в бакете по этому ключу уже лежит чужой state, что сделает terraform init -migrate-state?

Ответ

Terraform спросит, перезаписать ли существующий state локальным. Он ничего не склеивает. Ответ yes затрёт чужое состояние, поэтому читай вопрос и при сомнении отвечай no.

Шаги:

  1. В infra/terraform создай backend.tf. Каждая строка разобрана в теории («Remote backend»). Имя бакета подставит оболочка из $TF_BUCKET (команда cat > файл <<EOF записывает в файл всё до строки EOF, а $TF_BUCKET внутри заменяется значением), поэтому руками имя вписывать не надо. Выполни это в том терминале, где задан TF_BUCKET; в новом терминале сначала задай его снова, иначе в файле окажется пустое имя:
cd ~/notes/infra/terraform
cat > backend.tf <<EOF
terraform {
  backend "s3" {
    bucket = "$TF_BUCKET"
    key    = "notes/dev/terraform.tfstate"
    region = "ru-central1"

    endpoints = {
      s3 = "https://storage.yandexcloud.net"
    }

    # блокировка файлом в бакете; полагайся на неё только после проверки ниже
    use_lockfile = true

    # проверки, специфичные для AWS, в Yandex не нужны
    skip_region_validation      = true
    skip_credentials_validation = true
    skip_requesting_account_id  = true
    skip_s3_checksum            = true
  }
}
EOF

Проверь, что имя подставилось: grep bucket backend.tf должен показать bucket = "notes-tfstate-... с твоим суффиксом, а не пустые кавычки.

  1. Перенеси state. Флаг -migrate-state говорит: «backend поменялся, скопируй существующий state в новое место». Ответь yes на вопрос о копировании:
terraform init -migrate-state
  1. Проверь, что state теперь в бакете. Первая команда просит бакет перечислить объекты, jq -r '.contents[].key' оставляет только имена; вторая показывает, какие ресурсы знает Terraform:
yc storage s3api list-objects --bucket "$TF_BUCKET" --format json | jq -r '.contents[].key'
terraform state list
  1. Проверь блокировку. Если изменений нет, apply завершится сразу, без вопроса, и блокировку удержать не выйдет. Поэтому сначала сделай безопасное изменение: в vm.tf в ресурс yandex_compute_instance.notes добавь метку labels = { env = "dev" } (метка, label, это пометка «ключ = значение» на ресурсе, работе ВМ она не мешает, а Terraform применит её на месте, без пересоздания). Потом в первом терминале запусти apply и не отвечай на вопрос Enter a value (Terraform ждёт ответа, удерживая блокировку):
terraform apply

Во втором терминале нужен тот же набор переменных, что и в первом: ключ бакета, пароль из 7.2 (другой пароль дал бы в plan изменение user-data) и доступ к облаку из 7.1:

cd ~/notes/infra/terraform
export AWS_ACCESS_KEY_ID="$(jq -r .access_key.key_id ~/.notes-tf-key.json)"
export AWS_SECRET_ACCESS_KEY="$(jq -r .secret ~/.notes-tf-key.json)"
source ~/.notes-db-pass.env
export YC_TOKEN=$(yc iam create-token)
export YC_CLOUD_ID=$(yc config get cloud-id)
export YC_FOLDER_ID=$(yc config get folder-id)
terraform plan
  1. В первом терминале ответь yes: метка безвредна, а код и state снова совпадут. Повтори plan во втором: теперь он проходит и пишет No changes.

Что должно получиться: после init -migrate-state (вывод сокращён, смотри на вопрос о копировании и последние строки):

Initializing the backend...
Do you want to copy existing state to the new backend?
  ...
  Enter a value: yes

Successfully configured the backend "s3"! Terraform will automatically
use this backend unless the backend configuration changes.

terraform state list (порядок по алфавиту):

data.yandex_compute_image.ubuntu
yandex_compute_disk.data
yandex_compute_instance.notes
yandex_vpc_network.notes
yandex_vpc_security_group.notes
yandex_vpc_security_group_rule.egress
yandex_vpc_security_group_rule.ingress["http"]
yandex_vpc_security_group_rule.ingress["https"]
yandex_vpc_security_group_rule.ingress["ssh"]
yandex_vpc_subnet.notes

Во втором терминале, пока первый ждёт ответа:

Error: Error acquiring the state lock

Lock Info:
  ID:        3d2c6a1e-7f0b-4b5e-9d3a-0c6f7c1e2a44
  Path:      notes-tfstate-ab12/notes/dev/terraform.tfstate
  Operation: OperationTypeApply
  Who:       user@laptop

Точный текст первой строки зависит от версии. Если второй plan прошёл без ошибки, хранилище не поддержало условную запись и use_lockfile тебя не защищает: запускай Terraform только из CI с очередью и не полагайся на флаг.

Как читать вывод: в выводе init главное Successfully configured the backend "s3": с этого момента state живёт в бакете. В list-objects должен быть notes/dev/terraform.tfstate (и, пока идёт apply, рядом notes/dev/terraform.tfstate.tflock: это и есть блокировка). В state list те же 10 строк, что были до переезда: если их меньше, миграция не прошла. В ошибке про блокировку смотри Who и Operation: они показывают, кто держит и что делает.

Объясни себе:

  1. Где физически лежит блокировка и что будет с ней, если процесс terraform убить?
  2. Почему skip_* флаги нужны для Yandex, но их не нужно копировать в конфиг для настоящего AWS?

Типичные ошибки:

  • Error: No valid credential sources found: в этом терминале не выставлены AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY. Экспортируй их заново.
  • Error: Failed to get existing workspaces: ... InvalidAccessKeyId: ключ задан, но хранилище его не знает (опечатка, удалённый или чужой ключ). Проверь статический ключ сервисного аккаунта.
  • Warning: Deprecated Parameter ... "endpoint": старый синтаксис, он устарел с Terraform 1.6 и пока работает. Пиши endpoints = { s3 = "..." }.
  • Error: Backend initialization required, please run "terraform init": после правки backend.tf не выполнен init.
  • plan показывает ~ update in-place у ВМ и user-data (sensitive value): в терминале другой TF_VAR_notes_db_password, не тот, с которым создавалась ВМ. Верни прежний пароль. Если его уже нет, такой apply безвреден для работающей машины (cloud-init повторно не запускается), но state запомнит новое значение.

Задание 3. Модуль notes-vm и окружение dev

Здесь ты переносишь уже работающие ресурсы в модуль по образцу. Проследи, какие значения стали входными переменными, какие результаты модуль отдаёт наружу и как изменились адреса ресурсов в state. Проверь перенос через plan: неожиданное удаление или пересоздание нужно разобрать до apply.

Цель: вынести сеть, диск, группу безопасности и ВМ в модуль и вызвать его из envs/dev, не пересоздавая ресурсы.

Предскажи: если просто перенести файлы в модуль и вызвать его на том же state, что покажет plan: No changes или пересоздание? Что произошло с адресами ресурсов?

Ответ

Адреса стали вида module.notes_vm.yandex_vpc_network.notes. Для Terraform это новые ресурсы, а старые исчезли, поэтому plan предложит удалить всё и создать заново. Чтобы этого не случилось, нужны блоки moved (или terraform state mv).

Шаги:

  1. Сделай страховку и создай структуру. terraform state pull печатает текущий state, > пишет его в файл. mkdir -p создаёт каталоги (и не ругается, если они есть). git mv переносит файл и сообщает git, что это перенос. Файлы с секретами (terraform.tfvars) git не отслеживает, для них обычный mv. Файл backend.tf создан в задании 2 и ещё не отслеживается git, поэтому его сначала добавляют через git add, иначе git mv завершится ошибкой:
cd ~/notes/infra/terraform
terraform state pull > ~/notes-state-before-module.json   # страховка перед переездом
mkdir -p modules/notes-vm envs/dev
git mv network.tf variables.tf vm.tf outputs.tf cloud-init.yaml.tftpl modules/notes-vm/
git add backend.tf   # создан в задании 2 и ещё не в git, без этого git mv завершится ошибкой
git mv versions.tf providers.tf backend.tf .terraform.lock.hcl terraform.tfvars.example envs/dev/
mv terraform.tfvars envs/dev/
rm -rf .terraform tfplan terraform.tfstate*

В последней строке удаляются старый кэш .terraform/, файл плана из 7.2 и локальные остатки state: всё нужное уже лежит в бакете. Правила .gitignore из 7.2 (*.tfvars, tfplan) не привязаны к каталогу, поэтому новое место envs/dev они закрывают без правок.

Страховочный файл содержит секреты. Когда задание закончено, удали его: rm ~/notes-state-before-module.json.

  1. В modules/notes-vm файлы остались те же, что в 7.2, и менять в них почти ничего не нужно: variables.tf уже описывает входы (my_ip_cidr, ssh_public_key_path, image_family, vm_cores, data_disk_gb, notes_db_password), а outputs.tf выдаёт public_ip и data_disk_id. Это и есть интерфейс модуля. Шаблон cloud-init.yaml.tftpl лежит рядом с vm.tf, и путь ${path.module}/cloud-init.yaml.tftpl (path.module это каталог текущего модуля) продолжает работать.

  2. Создай вызов модуля, файл envs/dev/main.tf. Значения для входов модуля берутся из переменных корневого модуля (они объявлены ниже):

# Окружение dev вызывает типовой проект
module "notes_vm" {
  source = "../../modules/notes-vm"      # путь от этого каталога до модуля

  my_ip_cidr        = var.my_ip_cidr
  notes_db_password = var.notes_db_password
}

Дочернему модулю нужен свой versions.tf: каждый модуль сам говорит, откуда брать провайдера. Без него Terraform решит, что провайдер yandex принадлежит hashicorp (по умолчанию он ищет там), не найдёт его, и init упадёт. Создай modules/notes-vm/versions.tf (версию можно не указывать: её ограничивает корень):

terraform {
  required_providers {
    yandex = {
      source = "yandex-cloud/yandex"   # провайдер не из hashicorp, адрес указываем явно
    }
  }
}

Файл envs/dev/variables.tf (значения придут из terraform.tfvars и TF_VAR_notes_db_password, как в 7.2):

variable "my_ip_cidr" {
  type        = string
  description = "Внешний адрес с /32, откуда разрешён SSH"
}

variable "notes_db_password" {
  type        = string
  sensitive   = true
  description = "Пароль БД: только через TF_VAR, не в файле"
}

Файл envs/dev/outputs.tf: модуль отдаёт значения наружу только через output, а корневой модуль повторяет их, чтобы terraform output работал как раньше:

output "public_ip" {
  value = module.notes_vm.public_ip
}

output "data_disk_id" {
  value = module.notes_vm.data_disk_id
}
  1. Блоки moved лежат в корневом модуле, где менялись адреса. Файл envs/dev/moved.tf. Блок нужен для каждого управляемого ресурса (для data не нужен: это чтение, а не хранимый объект). Ресурс с for_each переносится одним блоком:
moved {
  from = yandex_vpc_network.notes
  to   = module.notes_vm.yandex_vpc_network.notes
}

moved {
  from = yandex_vpc_subnet.notes
  to   = module.notes_vm.yandex_vpc_subnet.notes
}

moved {
  from = yandex_compute_disk.data
  to   = module.notes_vm.yandex_compute_disk.data
}

moved {
  from = yandex_vpc_security_group.notes
  to   = module.notes_vm.yandex_vpc_security_group.notes
}

moved {
  from = yandex_vpc_security_group_rule.ingress
  to   = module.notes_vm.yandex_vpc_security_group_rule.ingress
}

moved {
  from = yandex_vpc_security_group_rule.egress
  to   = module.notes_vm.yandex_vpc_security_group_rule.egress
}

moved {
  from = yandex_compute_instance.notes
  to   = module.notes_vm.yandex_compute_instance.notes
}
  1. Установи модуль и проверь план. terraform init нужен, потому что появился блок module и backend теперь читается из нового каталога (state в бакете тот же, ключ не изменился):
cd envs/dev
source ~/.notes-db-pass.env   # пароль из 7.2
terraform init
terraform plan
  1. Примени проверенный план: перемещения адресов записываются в state только командой apply (plan ничего не сохраняет). Перемещения не создают и не удаляют ресурсы, поэтому apply безопасен, если в плане нет will be destroyed:
terraform apply
terraform plan -detailed-exitcode; echo "код выхода: $?"

Должно быть No changes и код 0. Без apply проверка в задании 5 вернула бы код 2.

  1. Второе окружение делается по образцу. В stage запустим только init и plan: apply создал бы вторую ВМ за твои деньги. Модуль один, состояний два.

    1. Скопируй envs/dev в envs/stage без каталога .terraform (там запомнены настройки backend от dev, и после смены key init начал бы предлагать миграцию) и удали moved.tf (в stage переносить нечего):

      cd ~/notes/infra/terraform/envs
      cp -r dev stage && rm -rf stage/.terraform stage/moved.tf
      
    2. В envs/stage/backend.tf поменяй key на notes/stage/terraform.tfstate. sed -i.bak правит файл на месте и оставляет копию .bak (форма работает и в Linux, и в macOS); grep покажет результат:

      sed -i.bak 's#notes/dev/terraform.tfstate#notes/stage/terraform.tfstate#' stage/backend.tf && rm stage/backend.tf.bak
      grep key stage/backend.tf
      
    3. Чтобы имена ресурсов не конфликтовали с dev, добавь в modules/notes-vm/variables.tf вход:

      variable "name_suffix" {
        type    = string
        default = ""
      }
      
    4. В коде модуля подставь суффикс в имена: "notes${var.name_suffix}" для сети и подсети (network.tf), "notes-data${var.name_suffix}" для диска и "notes-sg${var.name_suffix}" для группы безопасности, а в vm.tf в local.name используй "notes-vm${var.name_suffix}". Это делает sed; затем grep покажет, что получилось:

      cd ~/notes/infra/terraform/modules/notes-vm
      sed -i.bak -e 's/= "notes"$/= "notes${var.name_suffix}"/' -e 's/= "notes-data"$/= "notes-data${var.name_suffix}"/' -e 's/= "notes-sg"$/= "notes-sg${var.name_suffix}"/' -e 's/= "notes-vm"$/= "notes-vm${var.name_suffix}"/' network.tf vm.tf
      grep -n 'name_suffix' network.tf vm.tf
      rm -f network.tf.bak vm.tf.bak
      

      Блок в network.tf после правки выглядит так (в vm.tf и у диска и группы безопасности то же самое):

      resource "yandex_vpc_network" "notes" {
        name = "notes${var.name_suffix}"
      }
      

      Если grep показывает меньше пяти строк, имя у тебя записано иначе: поправь вручную. После правки dev-имена не меняются, потому что суффикс по умолчанию пустой. Заодно проверь это в envs/dev: git diff модуля должен менять только строки с name_suffix.

    5. В envs/stage/main.tf в блок module добавь строку name_suffix = "-stage".

    6. Запусти terraform init и terraform plan в envs/stage. Ожидай в конце вывода Plan: 9 to add, 0 to change, 0 to destroy.: state у stage пустой, поэтому Terraform создаст всё. Девять это ресурсы модуля: сеть, подсеть, диск, группа безопасности, три правила ingress, правило egress и ВМ (если у тебя набор другой, считай по своему коду). Затем вернись в envs/dev и проверь, что его plan по-прежнему No changes: у dev суффикс пустой по умолчанию.

Что должно получиться: plan показывает перемещения, а не пересоздание (вывод сокращён до характерных строк):

Terraform will perform the following actions:

  # yandex_vpc_network.notes has moved to module.notes_vm.yandex_vpc_network.notes
  # yandex_vpc_subnet.notes has moved to module.notes_vm.yandex_vpc_subnet.notes
  # yandex_compute_instance.notes has moved to module.notes_vm.yandex_compute_instance.notes
  ...

Plan: 0 to add, 0 to change, 0 to destroy.

ИИ: нейросеть удобно просить написать moved.tf по списку адресов из terraform state list, но результат всегда проверяй командой plan: ждёшь 0 to destroy.

Как читать вывод: каждая строка X has moved to Y значит: Terraform понял, что это один и тот же объект, и только перепишет его адрес в state. Смотри на итог: 0 to add, 0 to destroy значит, что ничего не пересоздаётся. Если видишь will be destroyed и will be created для одной и той же ВМ или сети, значит для неё нет блока moved или в нём опечатка в адресе: не применяй, а дополни moved.tf. После apply строки про moved исчезнут, а plan будет показывать No changes.

Объясни себе:

  1. Почему moved пишут в корневом модуле, а не внутри вызываемого?
  2. Что будет с envs/stage, если ты поменяешь код модуля? Как защититься от этого в команде?

Типичные ошибки:

  • Error: Module not installed: после добавления блока module не выполнен terraform init.
  • Error: Unsupported argument ... An argument named "vm_cores" is not expected here: в вызове модуля есть аргумент, для которого в модуле нет variable.
  • Error: Reference to undeclared module: имя в ссылке (module.notes_vm) не совпадает с именем блока module.
  • Error: Missing required argument ... "my_ip_cidr" is required: обязательная переменная модуля не передана в блоке module.

Задание 4. Зеркало провайдеров и lock-файл

Цель: настроить установку провайдера через зеркало и зафиксировать версии.

Предскажи: какой файл появится после init и почему его коммитят, а каталог .terraform/ нет?

Ответ

Появится .terraform.lock.hcl с версиями и хешами провайдеров. Его коммитят, чтобы у всех и в CI стояли одни и те же версии. Каталог .terraform/ это скачанные бинарники и кэш, он собирается заново и в git не нужен.

Шаги:

  1. Создай ~/.terraformrc (файл настроек Terraform для всего твоего пользователя). Адрес зеркала в примере условный, проверь актуальный адрес в документации Yandex Cloud:
provider_installation {
  network_mirror {
    url     = "https://terraform-mirror.yandexcloud.net/"   # проверь актуальный адрес
    include = ["registry.terraform.io/*/*"]                 # все провайдеры качаем с зеркала
  }
  direct {
    exclude = ["registry.terraform.io/*/*"]                 # напрямую не качаем ничего
  }
}

Зеркало должно отдавать все провайдеры, которые ты используешь (у нас это yandex-cloud/yandex и hashicorp/local, hashicorp/random, если они есть в коде), поэтому в include стоит шаблон на все. Если исключить из прямой загрузки только провайдер Yandex, то провайдеры HashiCorp пойдут на registry.terraform.io, а оттуда из России загрузка может не получиться. Честно: работает ли конкретное зеркало и что оно отдаёт, зависит от его сегодняшнего состояния, это надо проверить init-ом. Запасной вариант без сети: скачать архивы провайдеров заранее и положить в каталог, а в provider_installation указать filesystem_mirror { path = "/home/ты/.terraform-mirror" } (подставь свой путь), как в разделе про зеркало выше.

  1. Пересобери провайдеры и проверь код без применения. rm -rf .terraform удаляет кэш, init -upgrade заново выбирает версии в рамках ограничений и обновляет lock-файл, fmt -recursive приводит оформление всех .tf под каталогом к стандарту, validate проверяет синтаксис и ссылки без обращения к облаку:
cd ~/notes/infra/terraform/envs/dev
rm -rf .terraform
terraform init -upgrade
terraform fmt -recursive ../..
terraform validate

Что должно получиться (вывод init сокращён: версия провайдера у тебя может быть новее):

Initializing the backend...
Initializing modules...
Initializing provider plugins...
- Finding yandex-cloud/yandex versions matching "~> 0.232"...
- Installing yandex-cloud/yandex v0.232.0...
...
Terraform has been successfully initialized!

После validate:

Success! The configuration is valid.

В git status .terraform.lock.hcl виден как изменённый или новый файл: его нужно добавить в коммит.

Как читать вывод: строка Installing yandex-cloud/yandex vX показывает выбранную версию, она должна попадать под ограничение из versions.tf. Отдельной строки про зеркало Terraform не печатает: о том, что оно работает, говорит сам факт успешной загрузки. Success! The configuration is valid. значит, что код синтаксически верен, но не гарантирует, что облако его примет (это покажет plan).

Объясни себе:

  1. Что произойдёт, если в include оставить только yandex-cloud/*, а direct не трогать: откуда пойдёт провайдер HashiCorp и почему это может не сработать из России?
  2. Что произойдёт, если удалить .terraform.lock.hcl и запустить init через месяц?

Типичные ошибки:

  • Error: Failed to query available provider packages ... no available releases match the given constraints: нужной версии провайдера нет на зеркале. Ослабь ограничение в versions.tf или смени зеркало.
  • Error: Failed to install provider ... context deadline exceeded: registry недоступен, а зеркало не подхватилось. Проверь опечатки в ~/.terraformrc.

Задание 5. Шаг проекта: инфраструктура «Заметок» в git

Цель: зафиксировать в ~/notes модуль, окружение dev и backend.

Предскажи: какие файлы из infra/terraform должны попасть в коммит, а какие нет?

Ответ

В коммит: modules/notes-vm/* (.tf и шаблон cloud-init), envs/dev/*.tf (включая backend.tf и moved.tf), terraform.tfvars.example и .terraform.lock.hcl. Не в коммит: .terraform/, *.tfstate*, рабочий terraform.tfvars с реальными значениями. Файл ключа ~/.notes-tf-key.json лежит вне репозитория.

Шаги:

  1. Проверь структуру. find ... -type f перечисляет файлы, -not -path '*/.terraform/*' пропускает кэш, sort упорядочивает вывод:
cd ~/notes
find infra/terraform -type f -not -path '*/.terraform/*' | sort
  1. Убедись, что dev не хочет ничего менять. Флаг -detailed-exitcode делает код выхода информативным: 0 изменений нет, 1 ошибка, 2 изменения есть. $? это код выхода последней команды:
cd infra/terraform/envs/dev
terraform plan -detailed-exitcode
echo "код выхода: $?"
  1. Закоммить. .gitignore должен закрывать state и кэш (команда ниже допишет правила, если их нет; повтор безвреден). git status --short сначала покажет, что попадёт в коммит: убедись, что там нет tfvars и tfstate:
cd ~/notes
printf '%s\n' '*.tfstate*' '.terraform/' >> .gitignore
git status --short infra .gitignore
git add infra/terraform .gitignore
git commit -m "infra: модуль notes-vm, окружение dev, state в Object Storage"
git push

Что должно получиться: список файлов (порядок и набор могут отличаться; terraform.tfvars есть на диске, но .gitignore не пустит его в коммит):

infra/terraform/.gitignore
infra/terraform/envs/dev/.terraform.lock.hcl
infra/terraform/envs/dev/backend.tf
infra/terraform/envs/dev/main.tf
infra/terraform/envs/dev/moved.tf
infra/terraform/envs/dev/outputs.tf
infra/terraform/envs/dev/providers.tf
infra/terraform/envs/dev/terraform.tfvars
infra/terraform/envs/dev/terraform.tfvars.example
infra/terraform/envs/dev/variables.tf
infra/terraform/envs/dev/versions.tf
infra/terraform/modules/notes-vm/cloud-init.yaml.tftpl
infra/terraform/modules/notes-vm/network.tf
infra/terraform/modules/notes-vm/outputs.tf
infra/terraform/modules/notes-vm/variables.tf
infra/terraform/modules/notes-vm/versions.tf
infra/terraform/modules/notes-vm/vm.tf

И результат плана:

No changes. Your infrastructure matches the configuration.
код выхода: 0

Код лежит в твоём репозитории ~/notes/infra/terraform.

Как читать вывод: в списке должны быть оба каталога, envs/dev и modules/notes-vm, а в корне infra/terraform никаких .tf не осталось. No changes и код 0 значат, что переезд в модуль ничего не поменял в облаке: так и должно быть при рефакторинге. Код 2 значит, что plan хочет что-то поменять: читай план, не игнорируй. В git status --short строки начинаются с R (перенос) или A (новый файл); ?? напротив terraform.tfvars или tfstate означает, что .gitignore их не закрыл.

Объясни себе:

  1. Что означает код выхода 2 у plan -detailed-exitcode?
  2. Почему backend.tf лежит в envs/dev, а не в модуле?

Типичные ошибки:

  • fatal: pathspec 'infra/terraform' did not match any files: ты не в репозитории ~/notes.
  • В git status виден terraform.tfstate или envs/dev/terraform.tfvars: в .gitignore нет нужного правила (для state нужен шаблон *.tfstate*, для tfvars шаблон *.tfvars из 7.2). Добавь правила в .gitignore: printf '%s\n' '*.tfstate*' '.terraform/' >> ~/notes/.gitignore, и убери файл из индекса: git rm --cached <файл>.

Сломай и почини

Сценарии ручные: ломаешь командами, разбор в <details>. Работай в envs/dev.

Симптом

Выбери сценарий и воспроизведи:

  1. Конфликт state. В одном терминале запусти terraform apply и не отвечай, во втором сделай то же самое. Убей первый процесс через kill -9 и повтори terraform plan.
  2. Смена backend. Поменяй в backend.tf key на notes/dev2/terraform.tfstate и запусти terraform plan (увидишь Backend initialization required), затем terraform init без флагов (Backend configuration changed).
  3. Потеря state. Удали объект state из бакета: yc storage s3api delete-object --bucket "$TF_BUCKET" --key notes/dev/terraform.tfstate, затем terraform plan.

Гипотезы

  • Сценарий 1: блокировка осталась от убитого процесса, либо кто-то ещё реально работает.
  • Сценарий 2: state лежит в другом месте, а Terraform помнит старый backend в .terraform/.
  • Сценарий 3: Terraform видит пустой state и хочет создать всё заново.

Проверки

# объекты в бакете (файл блокировки, версии state)
yc storage s3api list-objects --bucket "$TF_BUCKET" --format json | jq -r '.contents[].key'
# что Terraform помнит о backend
jq '.backend.config' .terraform/terraform.tfstate

Разбор: первая команда перечисляет объекты бакета (в нём должны быть notes/dev/terraform.tfstate и, пока кто-то работает, .tflock). Вторая читает служебный файл .terraform/terraform.tfstate: это не твой state, а запись о том, какой backend Terraform запомнил при последнем init, и jq '.backend.config' достаёт из неё настройки backend.

Как читать вывод: если в бакете нет notes/dev/terraform.tfstate, state потерян (сценарий 3). Если .tflock есть, а процесса нет, блокировка зависла (сценарий 1). Если key в .backend.config не совпадает с backend.tf, вот причина сценария 2.

Исправление

Разбор сценариев

1. Блокировка от убитого процесса. Убедись, что никто больше не работает (спроси в чате, посмотри Who в сообщении). Затем сними блокировку по ID из ошибки:

terraform force-unlock 3d2c6a1e-7f0b-4b5e-9d3a-0c6f7c1e2a44

Дальше запусти plan: state мог остаться в промежуточном состоянии. force-unlock опасен, потому что разрешает параллельный apply. Хороший процесс: запуски идут только из CI с очередью.

2. Backend initialization required / Backend configuration changed. Terraform заметил, что описание backend не совпадает с запомненным, и не гадает, что ты хотел. Два честных варианта:

# перенести state в новое место
terraform init -migrate-state
# переключиться на другое место без копирования
terraform init -reconfigure

Ошибка защищает от ситуации, когда plan пойдёт по пустому state и предложит создать всё заново.

3. Потеря state. Сначала попробуй восстановить предыдущую версию объекта из бакета. Перечисли версии, скачай нужную и загрузи её как текущую (точные флаги сверь с yc storage s3api --help, формат может меняться):

yc storage s3api list-object-versions --bucket "$TF_BUCKET" --prefix notes/dev/terraform.tfstate
yc storage s3api get-object --bucket "$TF_BUCKET" --key notes/dev/terraform.tfstate --version-id "<id версии>" restored.tfstate
terraform state push restored.tfstate

Разбор:

  • Имя выходного файла (restored.tfstate) в get-object идёт последним позиционным аргументом, а не флагом. Сверь с yc storage s3api get-object --help.
  • <id версии> берётся из первого вывода.
  • Если state удалили, первой в списке может стоять метка удаления (delete marker, пометка «объект удалён», у неё нет содержимого). Её id брать нельзя: нужен id следующей по времени обычной версии.
  • Если state push отказывается (например, у файла номер версии state меньше, чем у лежащего в бакете), читай текст ошибки и не добавляй -force, пока не понял причину.

Если версий нет, ресурсы живы в облаке, а Terraform о них не знает. Тогда код у тебя уже есть, остаётся импортировать:

terraform import module.notes_vm.yandex_vpc_network.notes "<id сети из yc vpc network list>"
terraform import module.notes_vm.yandex_compute_instance.notes "<id ВМ из yc compute instance list>"
terraform plan

Повторяй импорт для каждого ресурса, пока plan не покажет No changes. Перед любой правкой state страхуйся: terraform state pull > backup.tfstate. Если apply оборвался на ошибке, Terraform может сохранить локальный errored.tfstate с тем, что не успел записать в бакет: не удаляй его, а отправь в бакет командой terraform state push errored.tfstate. Вывод: версионирование бакета включают до аварии, а не после.

ИИ в помощь

Нейросеть быстро разбирает чужой plan и подсказывает блок moved или import, но она не видит твой бакет и state. Общие правила работы с ней: ИИ-помощник.

Задача: составить блок moved для переноса ресурсов в модуль.

Я перенёс ресурсы network.tf и vm.tf в модуль module "notes_vm". Вот список адресов из terraform state list:
<вставь адреса>. Напиши moved.tf, чтобы plan не пересоздавал ресурсы. Для for_each-ресурсов используй один блок на весь ресурс.

Проверь ответ: запусти terraform plan: должно быть 0 to add, 0 to destroy и строки has moved to. Типичная ошибка: нейросеть пишет блок moved в дочернем модуле или путает направление from и to.

Задача: понять, что делать с зависшей блокировкой.

terraform apply упал с Error acquiring the state lock. Вот поля Lock Info: <вставь без секретов>.
Как понять, жив ли процесс, и когда безопасно делать force-unlock?

Проверь ответ: убедись, что она советует сначала выяснить, кто держит блокировку (Who), а после разблокировки сделать plan. Типичная ошибка: совет сразу запускать с -lock=false, это отключает защиту.

Задача: проверить настройки безопасности state.

Вот мой backend.tf и список прав сервисного аккаунта: <вставь без ключей>. Что здесь опасно для state, который содержит секреты?

Проверь ответ: сверь с разделом про права вокруг state: права только на бакет, публичный доступ выключен, версионирование включено. Типичная ошибка: нейросеть считает шифрование хранилища достаточной защитой.

Словарик урока

Термин Простыми словами
remote backend (удалённое хранилище state) Общее место (у нас бакет), где Terraform хранит state вместо файла на ноутбуке.
backend s3 Вариант backend для S3-совместимых хранилищ: Yandex Object Storage, AWS S3, MinIO.
бакет (bucket) Хранилище файлов в облаке: «шкаф с ячейками», где объект достаётся по имени-ключу.
ключ объекта (key) Имя файла внутри бакета, например notes/dev/terraform.tfstate; слэши это часть имени, а не настоящие каталоги.
versioning (версионирование) Режим бакета, при котором прошлые версии объекта не стираются: испорченный state можно откатить.
state lock (блокировка) Табличка «занято»: пока один процесс меняет state, другие ждут или получают ошибку.
use_lockfile Параметр backend: блокировка файлом .tflock в том же бакете (Terraform 1.10 и новее).
force-unlock Команда, снимающая «зависшую» блокировку по её ID. Использовать, только убедившись, что владелец не работает.
-migrate-state Флаг init: скопировать существующий state из старого backend в новый.
-reconfigure Флаг init: переключиться на новый backend без копирования state.
статический ключ доступа Пара «идентификатор + секрет» сервисного аккаунта; действует, пока его не отозвали.
module (модуль) Каталог с .tf файлами, который вызывают блоком module: «типовой проект» с входами и выходами.
корневой модуль (root module) Каталог, из которого запускают terraform; у нас envs/dev.
дочерний модуль (child module) Модуль, который вызвали из другого; у нас modules/notes-vm.
source Поле блока module: откуда взять модуль (путь, git, реестр).
адрес ресурса Полное имя ресурса в state: тип.имя, для модуля с префиксом module.<имя>..
moved Блок кода: «этот ресурс не новый, он просто сменил адрес». Защищает от пересоздания при рефакторинге.
terraform state mv Команда, меняющая адрес ресурса прямо в state (то же, что moved, но без следа в коде).
окружение (environment) Независимый набор инфраструктуры: dev, stage, prod.
workspace Отдельный state внутри одного backend при том же коде.
terraform import / блок import Привязка уже существующего объекта облака к блоку кода; пишет только state, код пишешь сам.
.terraform.lock.hcl Файл с точными версиями и хешами провайдеров; коммитится в git.
.terraform/ Кэш: скачанные провайдеры и запись о backend; в git не кладут.
зеркало провайдеров (provider mirror) Сервер с копией пакетов провайдеров, если основной registry недоступен.
~/.terraformrc Пользовательский файл настроек Terraform (где скачивать провайдеры).
-detailed-exitcode Флаг plan: код выхода 0 (изменений нет), 1 (ошибка), 2 (изменения есть).
endpoint Адрес «окошка» сервиса (API или хранилища), к которому обращается программа.

Вопросы с собеседований

Раздел для повторения: ответь вслух, потом открой ответ. Короткие вопросы с пометкой [на скорость] тренируй на время: ответ за 30 секунд.

1. [junior] [часто] Зачем хранить state Terraform удалённо и что такое блокировка?

Ответ

Локальный файл нельзя разделить с командой, и в нём лежат секреты. Удалённый state живёт в общем бакете с версионированием и доступом по правам. Блокировка не даёт двум apply работать одновременно: второй ждёт или падает с Error acquiring the state lock.

Что хотят услышать: секреты в state, общий источник правды, версионирование как страховка, lock, S3 плюс DynamoDB или use_lockfile.

Красный флаг: «храним state в git, репозиторий же приватный».

2. [junior] [часто] Как разделить окружения dev и prod: workspaces или каталоги?

Ответ

Каталоги с общими модулями: у каждого окружения свой backend, ключ и права, и видно, где я работаю. Workspaces компактнее, но легко перепутать текущий и применить изменения не туда, а права на бакет общие.

Что хотят услышать: плюсы и минусы обоих подходов, безопасность prod, права на state.

Красный флаг: «workspaces, потому что меньше файлов», без упоминания рисков.

3. [middle] Второй apply упал с Error acquiring the state lock. Что делаешь?

Ответ

Читаю сообщение: Who, Operation, время. Выясняю, работает ли владелец блокировки. Если запуск живой, жду. Если процесс убит или связь оборвалась, снимаю блокировку terraform force-unlock <ID> и сразу делаю plan, потому что state мог остаться в промежуточном состоянии.

Что хотят услышать: сначала выяснить, кто держит, потом force-unlock, после него plan, запуски через CI.

Красный флаг: «сразу -lock=false и применяю».

4. [middle] Кто-то удалил файл state из бакета. Что делаешь?

Ответ

Проверяю версионирование бакета и восстанавливаю предыдущую версию объекта. Если версий нет, ресурсы в облаке живы, а state пуст: сверяю код и делаю terraform import по каждому ресурсу, пока plan не покажет No changes. apply на пустом state не запускаю, иначе получу дубликаты или конфликт имён.

Что хотят услышать: версионирование, import, не запускать apply на пустом state, ограничение прав на запись в бакет.

Красный флаг: «создам всё заново, старые ресурсы удалю руками».

5. [middle] После переноса кода в модуль plan хочет удалить и создать ВМ. Почему и как исправить?

Ответ

Поменялись адреса ресурсов (появился префикс module.<имя>), а Terraform сопоставляет ресурсы по адресу. Исправляю блоками moved в корневом модуле или командой terraform state mv. После этого plan показывает только перемещение.

Что хотят услышать: адрес ресурса, moved, state mv, чтение плана до apply.

Красный флаг: «применил, ВМ пересоздалась, ничего страшного».

6. [middle] После правки backend.tf plan пишет Backend initialization required, а terraform init без флагов Backend configuration changed. Чем -migrate-state отличается от -reconfigure?

Ответ

Terraform сравнил конфиг backend с запомненным в .terraform/ и требует явного решения. -migrate-state копирует state из старого места в новое. -reconfigure просто переключает на новый backend без копирования, это годится, когда state уже перенесли руками или он не нужен.

Что хотят услышать: защита от plan по пустому state, различие флагов, осторожность с вопросом «перезаписать?».

Красный флаг: «удалю .terraform/ и всё заработает» без понимания последствий.

7. [middle] Когда выносить код в модуль и как версионировать модули?

Ответ

Когда код повторяется и меняется вместе (dev и stage), а не на всякий случай. У модуля есть переменные и outputs, внутренности наружу не торчат. Версию фиксирую: для git ?ref=v1.2.0, для реестра version = "~> 1.2". Локальный source годится, пока модуль живёт в одном репозитории, но тогда правки видят все окружения, и выкатываю их через dev.

Что хотят услышать: интерфейс модуля, версионирование, риск «поправил модуль и сломал все окружения».

Красный флаг: модуль на один ресурс и ссылка на ветку main вместо тега.

8. [middle] Ресурс создан руками в консоли, его просят «взять под Terraform». Как?

Ответ

Пишу описание ресурса в коде, делаю terraform import <адрес> <id> или блок import (Terraform 1.5 и новее), потом plan и правлю код, пока не получу No changes. Применяю только после этого, чтобы не изменить ресурс неожиданно.

Что хотят услышать: import не пишет код, цель No changes, осторожность с apply.

Красный флаг: «удалю и создам заново», если это база с данными.

9. [middle] В CI нужен plan на каждый pull request. Какие подводные камни?

Ответ

Для plan на PR CI нужен доступ к state: даже чтение берёт блокировку, значит ключу нужна и запись хотя бы на объект блокировки. Менять state этот ключ не должен. Параллельные PR могут мешать друг другу блокировкой; plan -lock=false допустим только осознанно и только для plan, не для apply. apply запускают отдельным ключом из защищённой ветки после merge и делают там новый plan -out: сохранённый план от PR уже устарел (Saved plan is stale), а сам файл плана это защищаемый артефакт, потому что в нём могут быть секреты. Ключи не лежат в репозитории (секреты CI), секреты в логах маскируют.

Что хотят услышать: разные ключи для plan и apply, lock на plan, новый plan после merge, секреты в плане и логах.

Красный флаг: «дадим CI админский ключ и отключим lock везде».

10. [middle] terraform init из РФ зависает на скачивании провайдера. Что делаешь?

Ответ

Проверяю сеть до registry, затем настраиваю зеркало в ~/.terraformrc: network_mirror должен отдавать все нужные провайдеры (не только yandex-cloud/*, иначе провайдеры HashiCorp пойдут напрямую и тоже могут не скачаться). Запасной вариант: filesystem_mirror с заранее скачанными архивами. Хеши в lock-файле не дадут зеркалу подложить другую сборку. В CI использую тот же файл или кэширую каталог плагинов.

Что хотят услышать: .terraformrc, зеркало для всех провайдеров, запасной filesystem_mirror, хеши в lock-файле.

Красный флаг: «качаю бинарник провайдера откуда попало и кладу руками».

11. [junior] Что коммитят из Terraform-каталога, а что нет?

Ответ

Коммитят .tf файлы и .terraform.lock.hcl (версии и хеши провайдеров, чтобы у всех и в CI были одни версии). Не коммитят .terraform/, *.tfstate* и *.tfvars с секретами.

Что хотят услышать: воспроизводимость версий, секреты в tfvars и state.

Красный флаг: «lock-файл в .gitignore, он мешает».

12. [junior] Что делают terraform state list, state show, state mv и state rm?

Ответ

Это команды для работы с state без изменения инфраструктуры. terraform state list показывает адреса ресурсов в state, terraform state show АДРЕС печатает атрибуты одного ресурса. terraform state mv меняет адрес ресурса в state, например после переименования или переноса в модуль, чтобы Terraform не пересоздавал его. terraform state rm убирает ресурс из state, сам ресурс в облаке остаётся, а Terraform о нём забывает. Перед mv и rm я делаю копию state (terraform state pull > backup.tfstate) и потом проверяю plan.

Что хотят услышать: работа только со state, mv для рефакторинга, rm не удаляет реальный ресурс, бэкап перед правкой, проверка plan после.

Красный флаг: «state rm удалит ВМ» или правка terraform.tfstate руками в редакторе.

Проверено на версиях

  • Terraform: 1.16.4 (как в уроках 7.1 и 7.2; для use_lockfile нужна версия 1.10 или новее)
  • Провайдер yandex-cloud/yandex: 0.232.0 (в коде ~> 0.232)
  • Yandex Cloud CLI (yc): версия не закреплена, проверь актуальную версию на странице проекта
  • Ubuntu: 26.04 LTS и 24.04 LTS
  • Не прогонялось: работа с реальным бакетом Yandex Object Storage (создание, миграция, блокировка) и перенос ВМ в модуль в облаке. Выводы в заданиях 2, 3 и 5 сокращены и показывают формат, на строки которого нужно смотреть. Поддержку use_lockfile в Yandex Object Storage проверь сам (задание 2).
  • Формат команд yc storage bucket update --grants ..., yc storage bucket get --full и yc storage s3api ... сверь с --help: они не прогонялись. Зеркало провайдеров и filesystem_mirror тоже не проверялись на реальной сети.

Итог урока: ты умеешь

  • умею создать бакет с версионированием и отдельным ключом сервисного аккаунта для state
  • умею перенести локальный state в S3-совместимый backend через terraform init -migrate-state
  • умею проверить, что блокировка работает, и снять зависшую через force-unlock
  • умею вынести сеть и ВМ в модуль и вызвать его из окружения без пересоздания ресурсов (moved)
  • умею развести dev и stage по каталогам с отдельными state
  • умею восстановить потерянный state из версии бакета или через terraform import
  • умею настроить зеркало провайдеров в ~/.terraformrc
  • умею объяснить на собеседовании разницу между workspaces и каталогами окружений

Дальше: Урок 7.4: Ansible: инвентарь, модули, ad-hoc

Проверь себя

Короткий тест по уроку: 5 вопросов из банка в 30. Засчитывается только полностью правильный ответ, порог 60%. Каждая новая попытка даёт другие вопросы, пока банк не закончится. Ответы видны после проверки.

Тест работает с включённым JavaScript.

тема 7 урок 7.3 3 ч курс 0/0 ← → уроки

Помоги улучшить курс

Что нужно изменить?