Terraform import徹底理解: 既存リソースの安全な取り込み

既存のクラウド資産をTerraform管理下に移す最初の一歩が terraform import です。import は“状態に写し込む”操作であり、設定ファイルそのものは自動生成しません。したがって、状態と設定の整合性をどう確保するかが肝になります。

本記事では、Terraform 1.5以降で推奨される import block と、引き続き使える従来の terraform import CLI の両方を、安全かつ試験対策の観点で比較・解説します。

取り込みの基本概念と前提

terraform import は既存リソースをTerraformの状態(tfstate)へ関連付ける操作です。これにより、そのリソースは以後terraform plan/applyの対象になります。ただしimport自体は設定(HCL)を生成せず、設定は手で用意する必要があります。

取り込みは「正しいアドレスへ、正しいIDで」行うことが全てです。対象リソースのID形式はリソースタイプごとに異なるため、プロバイダの公式ドキュメントで確認してください。また、認証情報とプロバイダ設定が事前に正しく構成されていることが前提です。

• importは既存の実体を破壊しない。tfstateへの対応付けのみ
• 設定は自動では生成されない。リソースブロックを書いて整合させる
• ID形式はリソースごとに異なる（例: aws_s3_bucket はバケット名、aws_iam_roleはロール名など）
• ワークスペース・バックエンド・ステートロックを適切に設定してから実行する

最小限のリソース定義の例（取り込み対象）

resource "aws_s3_bucket" "example" {
  bucket = "my-existing-bucket"
  # 実環境の属性に合わせて必要最小限から開始
}

tfstateとリソースアドレスの理解

importは“どこに紐づけるか”が重要です。Terraformのリソースアドレスは、モジュール階層・種類・名前・インデックス（count/for_each）で構成されます。誤ったアドレスに取り込むと、のちにリネームや再取り込みが発生し、リスクや手戻りにつながります。

dataソースは取り込み対象外です。importできるのはmanaged resourceのみです。モジュール配下へ取り込む場合は module.<name> の階層を含むフルアドレスを使います。

• トップレベル: aws_instance.web
• count付き: aws_instance.web[0]
• for_each付き: aws_instance.web["blue"]
• モジュール配下: module.app.aws_instance.web
• dataソースは不可、resourceのみが対象

代表的なアドレス指定例

# 単一
# terraform import aws_instance.web i-0123456789abcdef0

# countの0番目
# terraform import aws_instance.web[0] i-0aaa...

# for_eachのkey=blue
# terraform import aws_instance.web["blue"] i-0bbb...

# モジュール配下
# terraform import module.app.aws_instance.web i-0ccc...

実務フロー: import block方式（Terraform 1.5+）

Terraform 1.5以降は、設定にimport blockを宣言してからplan/applyで取り込むワークフローが推奨です。コードとしてレビューでき、再現性が高いのが利点です。import blockは to と id を指定します。to には取り込み先のリソースアドレス、id には既存リソースのIDを与えます。

import blockと対応するresourceブロックの双方が設定内にあることが前提です。planで差分を確認し、applyで状態に取り込みます。その後、必要に応じて属性を明示設定してドリフトを減らします。

• コードで管理できるため、PRレビューに乗せやすい
• plan結果にimportが現れるので、安全な適用判断が可能
• 取り込み後はimport blockを削除してもよい（履歴として残す運用も可）

import block方式の流れ

import blockと対応リソースの例（S3バケット）

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

import {
  to = aws_s3_bucket.example
  id = "my-existing-bucket"
}

# 実行
# terraform init
# terraform plan   # importされる提案を確認
# terraform apply  # 状態へ取り込み

レガシーCLI方式: terraform importコマンド

従来の terraform import ADDRESS ID も引き続き利用可能です。こちらは即時に状態へ書き込みます。取り込み後に設定がない（または属性不一致がある）と、次のplanで差分が多く出るため、取り込み前後で設定を整える運用が必要です。

モジュールやfor_each/countのアドレス指定に注意してください。誤ったアドレスへ取り込んだ場合は terraform state mv で移動できますが、計画的に行う方が安全です。

• コマンド一発で状態に反映されるため、素早いがレビューは難しい
• 設定が未整備だとplanが大きな差分を示す
• 誤取り込み時は terraform state rm / mv で調整可能

CLI方式の例とリカバリ操作

# 取り込み（IAMロール名で識別する例）
terraform import aws_iam_role.app_role app-role

# モジュール配下
terraform import module.app.aws_s3_bucket.logs my-log-bucket

# 誤取り込みを移動
terraform state mv aws_s3_bucket.wrong module.app.aws_s3_bucket.logs

# 誤取り込みを削除（リソース自体は削除されない）
terraform state rm aws_s3_bucket.wrong

よくある落とし穴とベストプラクティス

import直後にplanで大きな差分が出る場合、設定が実体を十分に表現できていません。強いデフォルトやcomputed属性に依存せず、実環境に合わせて明示設定するほどドリフトは減ります。特に暗号化、ライフサイクル、タグ、削除保護などは明示的に書きましょう。

count/for_eachやモジュール階層の導入は、取り込み前に決めておくと後の移動が減らせます。名前変更の必要が出た場合は movedブロックで安全にアドレスを移譲できます。大規模移行は一括ではなく、重要度の低いリソースから段階的に進め、ステートのバックアップを徹底します。

• 取り込み前に tfstate のバックアップを取る（リモートバックエンドでも念のため）
• ワークスペースを誤らない（defaultに本番を取り込まない）
• planで差分を精読。refresh-onlyの検討も有効
• 命名やモジュール設計を先に固める
• renameは moved ブロックで安全に

for_each取り込みとmovedブロックの例

# for_eachの例（タグ値ごとにキー管理）
resource "aws_kms_key" "keys" {
  for_each = toset(["blue", "green"])
  description = "key-${each.key}"
}

import {
  to = aws_kms_key.keys["blue"]
  id = "1234abcd-...-blue-key-id"
}
import {
  to = aws_kms_key.keys["green"]
  id = "5678efgh-...-green-key-id"
}

# アドレス変更の安全な移行
moved {
  from = aws_kms_key.keys["blue"]
  to   = module.security.aws_kms_key.keys["blue"]
}

試験対策ポイントと運用コマンド集

試験では「importは状態に取り込むだけで設定を作らない」「正しいリソースアドレスとIDを指定」「dataソースは対象外」「モジュール/for_each/countの扱い」「import blockと従来CLIの違い」が頻出です。apply前にplanで輸入提案が見えるのがimport block方式の特徴です。

運用では、取り込み後に terraform state show で状態を確認し、設定との差分を埋めることが重要です。誤取り込み時の state mv/rm、名前変更時の moved ブロック、状態のバックアップとロック、ワークスペースの使い分けを押さえておきましょう。

• importは破壊的でないが、間違うと復旧に工数がかかる
• 取り込み後に state show → 設定追記 → plan で差分を減らす
• ワークスペースとバックエンドの整合を常に確認

よく使う確認・調整コマンド

# 状態の中身を確認
terraform state list
terraform state show aws_s3_bucket.example

# ステートの安全な移動
terraform state mv aws_s3_bucket.old aws_s3_bucket.new

# ワークスペース切替
terraform workspace select staging

問題で確認

よくある質問