Terraform moved ブロック徹底解説: リファクタリング時の安全な移動

moved ブロックは、既存インフラの作り直しを避けつつ、アドレス（resource/module アドレス）の変更を宣言的に state に反映させる仕組みです。

チーム開発や CI/CD でのリファクタリング時に、手順ミスや環境差異を防げる点が最大の利点です。

moved ブロックの位置づけと使い所

リファクタリングでリソース名やモジュール構成を変更すると、Terraform のアドレスが変わり、従来のままでは plan に「古いリソースの destroy」と「新しいリソースの create」が並びます。既存リソースを壊したくない、ダウンタイムを出せない場合に、moved ブロックで旧→新アドレスの対応を宣言すると、apply 時に state 上の紐づけだけを移し替え、物理リソースはそのまま保持できます。

実務では、命名規則変更、モジュール化・モノレポ再編、count から for_each への移行などで頻出します。コマンドで個別に state を触るより、コードに変更履歴として残せるため、再現性・レビュー適性・CI 実行時の安全性が高いのが特徴です。

• 主な利用局面: リソース名のリネーム、モジュール間の移動、インスタンス index/key の変更（count→for_each など）
• 非対応: データソースの移動（data は state の管理対象ではない）
• メリット: 破壊的変更の回避、チームでの再現性、plan/apply による自動適用

最小例: リソース名のリネーム（state のみ移動、実体は不変）

resource "aws_s3_bucket" "app_primary" {
  # 旧: aws_s3_bucket.app
  # 設定内容は従来どおり
}

moved {
  from = aws_s3_bucket.app
  to   = aws_s3_bucket.app_primary
}

構文、アドレス、配置のルール

moved ブロックは Terraform 1.1 以降で利用可能です。書式は moved { from = <旧アドレス> to = <新アドレス> }。from/to は同一種類の state オブジェクト（同じリソースタイプ、同じ管理対象の粒度）を指す必要があります。タイプやプロバイダが異なる移動はできません。

moved ブロックは、from と to の両方のアドレスを参照できるモジュールに置きます。一般に「両者の最小共通の親モジュール」に配置すると覚えると安全です。例えば、ルート直下のリソースを子モジュールへ移す場合は、ルートモジュールに moved を書き、from はルートのリソース、to は module.<name>.<resource> の形式で指定します。

適用条件として、to 側のリソース（またはモジュール）は新しい構成としてコード上に存在し、state には未登録であること、from 側のオブジェクトは state に存在するがコード上には存在しない（あるいは rename 後で参照されていない）ことが必要です。plan には moved エントリとして表示され、apply 時に一度だけ消化されます。

• 配置原則: 両アドレスを同時に参照できる最小共通親モジュールに置く
• 型制約: リソースタイプ・プロバイダは不変（aws_s3_bucket→aws_s3_bucket は可、aws_s3_bucket→aws_s3_object は不可）
• 非対象: data ブロック、出力値、変数などの非 state オブジェクト
• 状態前提: to は state に未登録、from は state に登録済み
• 出力: plan に moved として表示、apply 後は無変更として扱われる

モジュール化に伴う移動（ルート→子モジュール）

# root module
module "storage" {
  source = "./modules/storage"
}

# 旧: aws_s3_bucket.app（root に存在していた）
# 新: module.storage.aws_s3_bucket.app（子モジュール配下に定義）

moved {
  from = aws_s3_bucket.app
  to   = module.storage.aws_s3_bucket.app
}

典型リファクタリング別の書き方

よくある 3 パターンを示します。いずれも、先に新しい定義（to 側のリソース/モジュール）をコードに用意し、同時に moved ブロックを追加して plan で moved のみになることを確認します。

count→for_each では、インスタンス単位のアドレスが変わるため、必要な数だけ moved を並べます。インデックス番号からキー名への対応を一意に決めるのがポイントです。

• リネーム: ラベルだけを変える単純移動
• モジュール移動: ルート↔子、子↔子 のいずれも最小共通親に moved を置く
• count→for_each: 旧 index と新 key のマッピングを moved で列挙

モジュール移動の視覚化

ケース別 moved の記述例

# 1) リソース名のリネーム（同一モジュール内）
resource "aws_s3_bucket" "app_primary" {}

moved {
  from = aws_s3_bucket.app
  to   = aws_s3_bucket.app_primary
}

# 2) ルート→子モジュールへの移動（ルートに記述）
module "storage" { source = "./modules/storage" }

moved {
  from = aws_iam_role.app
  to   = module.storage.aws_iam_role.app
}

# 3) count→for_each（index→key の対応を個別に指定）
# 旧: aws_instance.web[count = 2]
# 新: aws_instance.web[for_each = {"a" = ..., "b" = ...}]

moved {
  from = aws_instance.web[0]
  to   = aws_instance.web["a"]
}

moved {
  from = aws_instance.web[1]
  to   = aws_instance.web["b"]
}

moved と他手段の使い分け（比較表）

アドレス移動に近い操作はいくつかあります。どれを使うかは目的で決めます。既存リソースを壊さず、チームで再現したいなら moved が第一選択です。単発の緊急対応や過去のズレ補正には state コマンドを検討します。新規の外部リソース取り込みは import 系が適切です。

• moved: 宣言的・履歴に残る。plan/apply に統合され安全。
• terraform state mv: 即時・手動・一回限り。履歴に残らず、共同作業では再現しづらい。
• import（import ブロック/terraform import）: 既存実体を state に登録するための手段で、アドレス移動とは目的が異なる。
• replace（-replace フラグや lifecycle）: 作り直しを意図的に行う。移動ではない。

安全な移動の実務フロー（チーム/CI 向け）

移動は「新定義の追加」と「moved の追加」を同一変更として扱い、plan に create/destroy が出ないことを確認してから適用します。リモートバックエンドのロックを有効にし、環境ごとに段階適用します。

複数の moved を束ねる場合は、plan で期待どおりに全て moved と表示されるかを確認します。to 側が既に state に存在する場合はエラーになるため、重複を先に解消（state rm か destroy）してから進めます。

• ブランチで新しい定義と moved を同時に追加
• terraform plan を取り、moved のみが表示されることを確認
• 検証環境→ステージング→本番の順に apply（バックエンドロック必須）
• 全環境で適用完了後、moved ブロックを削除（将来のノイズ回避）
• CI では plan 出力に destroy/create が混ざっていないことをゲートにする

期待される plan 出力（概念例）

Terraform will perform the following actions:

  # aws_s3_bucket.app_primary has moved to aws_s3_bucket.app_primary
    moved from aws_s3_bucket.app
          to aws_s3_bucket.app_primary

Plan: 0 to add, 0 to change, 0 to destroy. 2 to move.

試験対策: よく出る論点と落とし穴

試験では、moved と import/replace/state mv の使い分け、モジュールどこに置くか、count→for_each の個別移動、to/from の前提条件、非対応対象（data）などが問われます。plan での挙動（moved が表示され、create/destroy は出ない）が読み取れることも重要です。

また、moved は型やプロバイダを跨いだ移動に使えない点、to 側が state に既にあると apply が失敗する点、apply 後は一度消化されるので全環境で確実に適用してから削除する運用が推奨される点も押さえておきましょう。

• 配置ルール: 両アドレスを参照できる最小共通親モジュールに置く
• 非対応: data ブロックの移動は不要/不可
• count→for_each: インスタンスごとに moved を書く（自動対応はされない）
• 型/プロバイダは不変であることが必要
• to はコードに存在し state には未登録、from は state に存在しコードには存在しないのが基本
• state mv は命令的、moved は宣言的（チームでの再現性は moved が優位）

問題で確認

よくある質問