Как добавить существующий ресурс в Terraform или OpenTofu через import

Хранилище создали вручную, теперь его нужно передать под управление кодом. Если просто добавить resource, инструмент видит новое объявление без привязки в state и предлагает создание. Одинаковое имя в облаке не означает, что Terraform или OpenTofu автоматически выберет существующий объект.

Import связывает удалённый объект с конкретным адресом конфигурации. При этом код должен описывать желаемое состояние. Импорт не доказывает, что параметры совпали, и не отменяет последующий update или replacement. Поэтому основная работа — проверить адрес, идентификатор объекта и план сразу после чтения текущего состояния.

Возьмём существующий S3 bucket

Ниже пример для обычного S3 bucket в AWS. Подставьте имя своего уже существующего учебного bucket и его регион. Нужны доступ на чтение этого объекта и заранее выбранная версия AWS provider в принятом lock-файле. Не используйте случайное имя: так вы будете разбирать другой объект или ошибку его отсутствия.

terraform {
  required_providers {
    aws = {
      source = "hashicorp/aws"
    }
  }
}

provider "aws" {
  region = "eu-central-1"
}

resource "aws_s3_bucket" "archive" {
  bucket = "existing-training-archive-12345"
}

import {
  to = aws_s3_bucket.archive
  id = "existing-training-archive-12345"
}

В этом типе ресурса строковый import ID — имя bucket. У других ресурсов формат бывает составным, поэтому не подставляйте ARN вместо ID по привычке. Контракт импорта aws_s3_bucket следует сверять с версией провайдера, выбранной проектом.

Просмотрим импорт до записи state

Выберите команды используемого продукта. Для Terraform декларативные import blocks требуют версии 1.5 или новее; в OpenTofu они поддерживаются, но новые возможности import зависят от версии. Здесь используется базовый строковый id, а не более новый identity.

terraform init
terraform plan -out=import.tfplan
terraform show -no-color import.tfplan

tofu init
tofu plan -out=import.tfplan
tofu show -no-color import.tfplan

Plan должен распознать импорт в aws_s3_bucket.archive. Внимательно прочитайте действия помимо него: теги и другие свойства могут отличаться от текущих. Минимальный resource в примере не означает полного описания конфигурации bucket и всех связанных настроек. Версионирование, политики и шифрование могут управляться отдельными ресурсами провайдера.

Если ожидается только привязка, сначала приведите конфигурацию к фактическому согласованному состоянию и добейтесь отсутствия неожиданных изменений. После одобрения применение сохранённого плана импортирует объект и выполняет другие перечисленные действия. Не воспринимайте apply import-плана как операцию, которая принципиально не способна изменить инфраструктуру.

Адрес должен быть единственным владельцем

Проверьте backend и workspace до импорта. Один объект не должен оказаться под независимым управлением в двух состояниях. Если bucket уже ведёт другой проект, сначала согласуйте передачу владения, иначе разные конфигурации начнут возвращать свои значения.

Для ресурса внутри модуля to включает путь module, для for_each — ключ экземпляра. Именно этот адрес должен существовать в конфигурации. Ошибка ключа может привязать объект не к тому логическому назначению, даже если сам ID указан правильно. До применения сравните адрес с ожидаемой структурой модуля.

Чем отличается команда import

CLI terraform import или tofu import тоже связывает объект со state, но делает запись во время самой команды и обычно требует заранее подготовленную конфигурацию. Блок import удобен для ревью: намерение видно в Git, а результат включён в план. Возможность генерации конфигурации — отдельный рабочий процесс; сгенерированные поля всё равно нужно осмыслить.

В текущих версиях Terraform и OpenTofu доступны дополнительные варианты выбора объектов, но поддержка identity определяется и версией CLI, и схемой провайдера. Для переносимого базового сценария достаточно проверенного строкового ID.

После импорта выполните новый обычный plan. Он должен объяснять дальнейшее управление объектом без предложения повторного создания. Сохраните запись о том, какое состояние стало владельцем и какие связанные настройки пока управляются отдельно. Тогда следующий разработчик увидит границу ответственности, а не только успешно выполненный import.

Ещё по теме

• Как переименовать ресурс Terraform или OpenTofu без пересоздания: moved
• Terraform и OpenTofu хотят пересоздать ресурс: как разобраться с планом

Продолжить изучение

Хотите управлять инфраструктурой через код и понимать последствия изменений? Plan, state, модули и работа с существующими ресурсами — темы программы «Terraform и OpenTofu: инфраструктура как код».