Если ресурс уже существует в облаке, одноимённый resource block не связывает его с Terraform автоматически. Обычный plan может предложить создать второй объект, а попытка быстро исправить ситуацию через apply закончится конфликтом имени или появлением дубля. Безопасный первый шаг — остановить изменения и связать три сущности: реальный remote ID, адрес в configuration и запись в state.

Import нужен только для объекта, которого нет в выбранном state. Если объект уже записан в state, но его параметры изменили вручную, это drift и его разбирают планом. Если похожий объект находится в другом workspace или state, сначала решают вопрос владельца: один remote object должен соответствовать одному Terraform resource address.

Сначала определяем, что именно разошлось

НаблюдениеКласс ситуацииСледующий шаг
Объект есть в cloud, address отсутствует в stateUnmanaged resourceПодготовить resource и import block
Address есть, параметры отличаютсяConfiguration driftОткрыть normal и refresh-only plan
Тот же remote ID найден в другом stateДвойное владениеОстановить оба pipeline и выбрать владельца
Plan предлагает второй объект с похожим именемНет связи по IDНе применять; проверить import ID
Import прошёл, но plan показывает replaceКонфигурация не совпала с immutable полямиСверить provider schema и аргументы

Имя в консоли не всегда является import ID. У разных providers идентификатором может быть UUID, составная строка, путь или набор identity attributes. Формат берут из документации конкретного resource type, а не угадывают по URL интерфейса.

Фиксируем исходное состояние без записи в state

terraform version
terraform workspace show
terraform state list
terraform plan -refresh-only -out=refresh.tfplan
terraform show -no-color refresh.tfplan > refresh-plan.txt
terraform plan -out=normal.tfplan
terraform show -no-color normal.tfplan > normal-plan.txt

Команды запускают только после проверки backend, workspace, credentials и provider region. Saved plan и state способны содержать чувствительные значения, поэтому их хранят как закрытые артефакты и не прикладывают в открытый тикет. Refresh-only plan показывает изменения известных объектов и сам по себе не обнаружит ресурс, которого нет в state.

Не используйте устаревший terraform refresh как диагностическую команду: он записывает обновлённое состояние без отдельного просмотра. Официальная документация рекомендует refresh-only plan и apply, причём apply выполняют только после анализа результата. Для принятия вручную созданного объекта нужен import, а не refresh.

Import описываем рядом с будущим владельцем

resource "example_service" "billing" {
  name   = "billing-prod"
  region = "example-region"
}

import {
  to = example_service.billing
  id = "provider-specific-remote-id"
}

Тип ресурса, region и ID в примере условны. Import block участвует в обычном plan, поэтому изменение видно в code review. Terraform требует destination resource block либо может сгенерировать начальную конфигурацию через plan с generate-config-out. Сгенерированный файл не считают готовым desired state: в нём нужно проверить defaults, computed fields, secrets и параметры, изменение которых вызывает replacement.

  • Импортировать один remote object только в один address.
  • Сначала работать с небольшой независимой группой, а не всей подпиской.
  • Не добавлять lifecycle ignore_changes ко всем полям ради пустого плана.
  • Не передавать state между командами вручную, если backend уже поддерживает locking.
  • Сохранить доказательство владельца: repository, module, workspace и on-call team.
  • Проверить зависимости, которые создавались вручную вместе с объектом.

Первый план после import читаем построчно

Успешный import означает только появление связи в state. Он не доказывает, что configuration описывает объект правильно. После импорта normal plan может предложить in-place update, replacement или destroy связанного ресурса. Каждое изменение классифицируют: принять текущее значение в код, осознанно привести объект к стандарту или временно отложить поле с конкретным владельцем и сроком.

Особое внимание — сетям, дискам, базам, encryption keys и identity. Поле ForceNew или его аналог у provider превращает безобидную на вид разницу в replacement. Не применяйте saved plan, если после его создания изменились configuration, provider credentials или внешний объект; создайте новый plan и снова проведите review.

Приёмка заканчивается повторяемым планом

  1. Проверить, что import затрагивает ожидаемый address и remote ID.
  2. Убедиться, что нет незапланированных create, replace и destroy.
  3. Разобрать все in-place changes и подтвердить их владельцем сервиса.
  4. Применить маленький проверенный plan через обычный review workflow.
  5. Сразу получить новый plan на той же revision конфигурации.
  6. Запретить ручные изменения либо описать аварийный процесс их последующего возврата в код.
  7. Добавить регулярный plan в CI без автоматического применения drift.

Если повторный plan пуст, это ещё не повод импортировать следующий набор вслепую. Сначала проверьте работу сервиса и метрики объекта. Для разбора подготовьте provider и Terraform versions, backend/workspace, обезличенные addresses и remote IDs, оба plan без секретов и список решений по каждому изменению.

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