Не подтверждайте неожиданный 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.jsonSaved plan и его JSON могут содержать конфиденциальные значения из конфигурации и state. Храните файлы как секретный artifact с коротким сроком жизни и не прикладывайте их целиком к публичной задаче. Для сравнения обычно достаточно обезличенных resource address, actions и changed attributes.
Одинаковый update бывает вызван разными слоями
| Признак в плане | Вероятный источник | Следующая проверка |
|---|---|---|
| Изменился provider version в lock | Upgrade действительно состоялся | Release notes и schema нужного ресурса |
| Remote value отличается и на старой версии | Ручной drift или внешний controller | Audit log облака и refresh-only plan |
| Значение сменило форму, смысл тот же | Новая нормализация provider | State до/после и 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 выпускаем отдельно от изменения ресурсов
- Создать отдельную ветку только для constraint и lock-файла.
- Запустить init -upgrade в чистом рабочем каталоге.
- Сохранить версии и checksums в результатах CI.
- Получить полный plan для тестового окружения.
- Проверить каждый replace и изменение чувствительных ресурсов.
- Применить canary там, где provider и платформа это допускают.
- Только после проверки повторить 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 передавать не нужно.