Не подтверждайте неожиданный plan только потому, что HCL не менялся. Provider переводит удалённый API в модель Terraform: новая версия может изменить default, нормализацию значения, тип поля или правило ForceNew. Сначала сохраните доказательства, затем сравнивайте версии на одном и том же state.

Самый безопасный первый результат — понять, что именно изменилось: выбранный бинарник provider, удалённый объект после refresh или конфигурация. Откат provider без снимка lock-файла и плана стирает эту границу и усложняет расследование.

Три снимка до разбора diff

terraform version
terraform providers
git diff -- .terraform.lock.hcl

terraform plan -out=upgrade.tfplan
terraform show -json upgrade.tfplan > upgrade-plan.json

Saved plan и его JSON могут содержать конфиденциальные значения из конфигурации и state. Храните файлы как секретный artifact с коротким сроком жизни и не прикладывайте их целиком к публичной задаче. Для сравнения обычно достаточно обезличенных resource address, actions и changed attributes.

Одинаковый update бывает вызван разными слоями

Признак в планеВероятный источникСледующая проверка
Изменился provider version в lockUpgrade действительно состоялсяRelease notes и schema нужного ресурса
Remote value отличается и на старой версииРучной drift или внешний controllerAudit log облака и refresh-only plan
Значение сменило форму, смысл тот жеНовая нормализация providerState до/после и issue/release note
Появился replace вместо updateАтрибут стал immutable или ForceNewПричина replace в plan JSON
План различается только в CIДругой lock, platform или variablesРабочий каталог, lock и input variables CI

Lock-файл фиксирует выбор, constraint задаёт коридор

Terraform хранит выбранные версии providers и checksums в .terraform.lock.hcl. Обычный terraform init повторно выбирает зафиксированную версию, а init -upgrade игнорирует прежний выбор и ищет новейшую версию внутри version constraints. Поэтому lock-файл нужно коммитить и менять тем же review, что и инфраструктурный код.

Широкий constraint без lock-файла делает чистый checkout непредсказуемым. Обратная крайность — вручную править version и hashes в lock-файле. Версию выбирает terraform init или terraform providers lock; человек проверяет diff и источник пакета.

Refresh-only отделяет внешний drift

Если подозрение падает на изменения вне Terraform, создайте terraform plan -refresh-only в изолированном рабочем процессе. Он показывает, как remote objects обновили бы state, не предлагая привести инфраструктуру к HCL. Это диагностический шаг, а не автоматическое разрешение принять любой drift.

  • Сравнить refresh-only результат на прежней и новой версиях provider.
  • Отметить computed, optional и явно заданные attributes.
  • Проверить, не добавляет ли policy/controller значения после apply.
  • Найти точную причину replace, а не считать символы в diff.
  • Не использовать -target как постоянный способ скрыть остальные изменения.

Upgrade выпускаем отдельно от изменения ресурсов

  1. Создать отдельную ветку только для constraint и lock-файла.
  2. Запустить init -upgrade в чистом рабочем каталоге.
  3. Сохранить версии и checksums в результатах CI.
  4. Получить полный plan для тестового окружения.
  5. Проверить каждый replace и изменение чувствительных ресурсов.
  6. Применить canary там, где provider и платформа это допускают.
  7. Только после проверки повторить plan для production.

Когда upgrade смешан с переименованием ресурсов, refactor модулей и ручным импортом, причину diff невозможно доказать. Отдельный PR позволяет откатить выбор provider, не откатывая бизнес-изменение.

Понижение версии тоже требует плана

Старый provider может не понимать state, записанный новой схемой, а удалённый API уже мог принять изменение. Поэтому rollback начинается с документации совместимости и нового plan; копирование старого lock-файла не отменяет выполненный apply. State backup нужен для аварийного восстановления, но его нельзя подменять поверх текущего state без отдельной процедуры.

Критерий успешного обновления

После согласованного apply повторный plan должен быть пустым на той же версии, с тем же lock-файлом и variables. Затем повторите запуск в чистом CI runner: локальный plugin cache не должен быть единственной причиной стабильности. Зафиксируйте provider version, lock diff и перечень ожидаемых resource actions в release record.

Что подготовить для точного разбора

Нужны Terraform version, блок required_providers, обезличенный diff .terraform.lock.hcl, список resource actions до и после upgrade, backend/workspace и release notes выбранного provider. Secrets, полный state и saved plan передавать не нужно.

Проверенные источники