В Terraform-конфигурации нужно переименовать ресурс (например, aws_instance.web в aws_instance.app) или завести под управление Terraform уже существующий вручную созданный ресурс, не удаляя и не создавая заново реальную инфраструктуру. Как использовать terraform state mv и terraform import для этих задач, и в чём риск, если пропустить этот шаг?

Короткий ответ

terraform state mv меняет адрес ресурса внутри state без обращения к облачному API, что позволяет переименовать или переместить ресурс в конфигурации без его пересоздания; terraform import добавляет в state привязку между уже существующим реальным ресурсом и адресом ресурса в конфигурации (начиная с Terraform 1.5 то же можно делать декларативно через блок import); если просто переименовать ресурс в коде без state mv, Terraform решит, что старый ресурс нужно удалить, а новый создать, что может вызвать простой.

Как это работает подробнее

Terraform сопоставляет блоки конфигурации с объектами в state по адресу ресурса (тип.имя или с учётом модуля); если адрес в коде не совпадает с адресом в state, Terraform считает старый объект «удалённым из конфигурации» и планирует destroy, а новый блок — созданием нового ресурса, даже если по факту это один и тот же облачный объект.

Пример кода

example.txtКопировать

# переименование ресурса без пересоздания
$ terraform state mv aws_instance.web aws_instance.app
# привязка уже существующего ресурса (id из облака) к конфигурации
$ terraform import aws_instance.app i-0abcd1234ef567890
# альтернатива в Terraform 1.1+ прямо в конфигурации
moved {
  from = aws_instance.web
  to   = aws_instance.app
}

Что использовать на практике

• Практика. перед state mv и import обязательно делается backup state (terraform state pull > backup.tfstate), затем выполняется команда, после чего обязательно запускается terraform plan, который должен показать No changes (для mv) или минимальные изменения, связанные с доведением атрибутов до соответствия конфигурации (для import, где часть атрибутов может быть не указана в коде); для множества ресурсов в Terraform 1.1+ удобнее декларативный блок moved, который фиксирует переименования в самой конфигурации и не требует ручных команд при каждом apply.

Подводные камни

• Ошибка. частая ошибка — переименовать ресурс в .tf-файле и сразу запустить apply, не проверив план, что приводит к неожиданному destroy/create на проде; при import — забыть прописать в конфигурации все атрибуты, которые реально заданы у существующего ресурса, из-за чего следующий plan попытается привести ресурс к дефолтным/неверным значениям.