Terraform import ブロック徹底攻略: 宣言的インポートで既存資産を安全に取り込む

既存のクラウド資産をTerraformの管理下に入れるとき、これまでは対話的な CLI インポートが主流でした。Terraform 1.5以降は import ブロックで宣言的に実施できます。

この記事では、宣言的インポートの基本、for_each/countやモジュール配下への取り込み、差分や生成コンフィグの扱い、試験での出題ポイントを実務レベルで整理します。

宣言的インポートの前提と試験ポイント

import ブロックは、既存リソースの「プロバイダ固有のインポートID」をTerraform状態に関連付ける宣言です。計画・適用のタイミングで評価され、対象のアドレスへインポートを実行します。データソースは対象外で、管理対象リソースのみがインポートできます。

従来の terraform import (CLI) が命令的手順だったのに対し、import ブロックはコード化されるため、コードレビューや再現性、CI/CDへの組み込みが容易です。適用後は import ブロックを削除しても状態は維持されますが、同じアドレスを重複インポートしようとするとエラーになります。

試験では次が問われやすいです: どのアドレスに取り込むか（count/for_eachやモジュール経路の指定）、インポートIDの形式の理解（プロバイダ依存）、差分発生時の挙動（計画での変更提案）、生成コンフィグの役割と限界、CLI と宣言的手法の使い分け。

• import ブロックは to と id を最低限指定する
• モジュール配下へも module.path.resource の完全修飾アドレスで指定可能
• for_each/count で作られた個別インスタンスは [key]/[index] を明示する
• 計画時に差分が出るのは正常。段階的に lifecycle.ignore_changes を活用
• 一部リソースはプロバイダがインポート非対応（providerのドキュメント要確認）

import ブロックの基本構文と最小例

最小構成は to（取り込み先のリソースアドレス）と id（既存リソースのインポートID）です。インポートIDはプロバイダのドキュメントに準拠します。例えば AWS の一部リソースは ARN、S3 バケットは名称、VPC は vpc-xxxx のようなIDを使います。

適用フローはシンプルで、計画時に取り込みが検出され、適用時に状態へ登録されます。その後、リソース定義と実体の差分があれば、通常の変更計画として提示されます。

• 複数の import ブロックを同一モジュール内に並べられる
• 対象リソースの定義が存在しない場合、計画時に生成コンフィグ出力オプションで雛形を得られる（Terraform 1.5以降）
• インポート成功後、import ブロックは恒久的に必要ではない（状態は保持される）

宣言的インポートの流れ

 既存クラウド資産           import ブロック           Terraform 状態
        |                         |                        |
        |  インポートID参照       |                        |
        |------------------------>|  to=addr / id=...      |
        |                         |   (plan/apply時評価)   |
        |                         |----------------------->|
        |                         |      状態に関連付け     |
        |                         |<-----------------------|
        |                         |  以後は通常の差分検出   |

最小例（AWS S3 バケットを取り込む）

provider "aws" {
  region = var.region
}

resource "aws_s3_bucket" "example" {
  bucket = "my-existing-bucket-123"
  acl    = "private"
}

# 宣言的インポート
import {
  to = aws_s3_bucket.example
  id = "my-existing-bucket-123"
}

# 実行例
# terraform init
# terraform plan
# terraform apply

for_each / count / モジュール配下のインポート

for_each や count で作られた個別インスタンスを取り込む場合、アドレスにキーまたはインデックスを明示します。多数の取り込みがあるなら、import ブロック自体に for_each を用いて宣言的に一括化できます（Terraform 1.5以降）。

モジュール配下のリソースは module. 経路を含む完全修飾アドレスを指定します。階層が深い場合も同様で、module.a.module.b.resource["key"] のように書きます。

• count の場合: aws_instance.web[0] のようにインデックス指定
• for_each の場合: aws_security_group.sg["admin"] のようにキー指定
• import ブロックの for_each で多数インポートをコード化し、レビューと再現性を担保
• モジュール配下: to = module.net.aws_vpc.main のように完全修飾アドレスを使う

アドレス指定の具体例

# count で作られた 0 番目のインスタンスを取り込む
resource "aws_instance" "web" {
  count         = 2
  ami           = var.ami
  instance_type = "t3.micro"
}

import {
  to = aws_instance.web[0]
  id = "i-0ab1c2d3e4f5"
}

# for_each の個別キーを取り込む
resource "aws_security_group" "sg" {
  for_each = {
    admin = "sg-admin"
    app   = "sg-app"
  }
  name = each.value
  vpc_id = var.vpc_id
}

import {
  to = aws_security_group.sg["admin"]
  id = "sg-0123456789abcdef0"
}

# import ブロックに for_each を使って一括宣言
variable "buckets" {
  type = map(string) # key=論理名, value=実在バケット名
}

resource "aws_s3_bucket" "b" {
  for_each = var.buckets
  bucket   = each.value
}

import {
  for_each = var.buckets
  to = aws_s3_bucket.b[each.key]
  id = each.value
}

# モジュール配下の取り込み
module "net" {
  source = "./modules/network"
}

import {
  to = module.net.aws_vpc.main
  id = "vpc-0abc123def456"
}

差分・生成コンフィグ・安全な移行手順

インポート直後は、既存リソースと現在のリソース定義が一致しないことが多く、計画に多数の変更が出ます。段階的移行では、まず安全に取り込むことを優先し、必要に応じて lifecycle.ignore_changes で過剰な差分を一時的に抑制し、設定の収斂後に外すのが現実的です。

Terraform 1.5以降では、対象リソースの定義がまだ無い場合に、計画時のオプションで生成コンフィグを出力できます。これは雛形生成であり、完全一致を保証するものではない点に注意してください。生成物はレビューして必要な属性のみを採用します。

• まず取り込む → 状態のバックアップ → 差分の意味を精査 → 小さく適用
• ignore_changes は最小限にし、段階的に外す
• 生成コンフィグはあくまでたたき台。プロバイダ既定値や不要属性に留意
• インポートIDは正確に。誤ったIDは apply エラーや意図せぬ差分の原因

一時的な差分抑制の例

resource "aws_s3_bucket" "example" {
  bucket = "my-existing-bucket-123"

  lifecycle {
    ignore_changes = [
      acl,                   # 現状のACLを一旦尊重
      versioning,            # 後で計画的に揃える
    ]
  }
}

# 収斂が済んだら ignore_changes を削除し、改めて計画・適用

CLI terraform import との比較と使い分け

小規模・単発なら CLI でも実務上は足りますが、チーム開発や再現性が重視される現場では import ブロックが有利です。レビュー可能なコードとして残せるため、監査性も高まります。一方、対話的な検証を素早く行う場面では CLI の手軽さも有効です。

生成コンフィグの自動出力や多数同時インポートの表現力は import ブロックが強みです。既存 IaC 標準や運用体制に合わせて併用を検討しましょう。

• チーム開発・CI/CD・監査性重視 → import ブロック中心
• スポット作業・試行錯誤 → CLI で素早く試す
• どちらでも状態は同じ成果に到達するが、履歴性と再現性の差が大きい

落とし穴とトラブルシュート

よくあるつまずきは、すでに状態に登録済みのアドレスを再度インポートしようとしてエラーになるケース、インポートIDの誤り、プロバイダや別リージョン・エイリアスの取り違えです。まず terraform state list で現状を把握し、アドレスとID、プロバイダ選択を見直します。

インポートはリソース実体を変更しません。状態への関連付けのみを行い、その後の差分調整で初めて変更が発生します。影響範囲が大きい場合は、対象ワークスペースのバックアップを取ってから段階的に進めてください。

• resource already managed エラー時は import ブロックを外すか、正しいインスタンスアドレスに修正
• インポートIDの形式はプロバイダ依存。ARNか名称かを事前確認
• provider alias/region の取り違えに注意（同名資産が別リージョンに存在しないか）
• 差分が大きいときは ignore_changes とスコープ分割で安全に収斂
• 状態破損に備え terraform state pull でバックアップを取得してから作業

現状確認の最小コマンド例

# 現在の状態にあるアドレス一覧
terraform state list

# 特定アドレスの詳細
terraform state show aws_s3_bucket.example

# 必要に応じてバックアップ
terraform state pull > state-backup.jsonl

問題で確認

よくある質問