Terraform state mv 徹底攻略: リソース移動の設計と落とし穴

terraform state mv は、実インフラには触れず「状態ファイル内のアドレス」を移動させる専用コマンドです。リソース名の変更、モジュールへの切り出し、count/for_eachの再設計など、リファクタリング時の安全装置になります。

ただし、使い所と手順を誤ると、次回 apply で意図しない作成・破壊が起こり得ます。本稿では公式ドキュメントの挙動に基づき、実務での手順と試験で問われる要点を最小限のリスクで押さえます。

state mv の基本と前提

terraform state mv は、SOURCE アドレスから DESTINATION アドレスへ、状態上の関連付けを移すコマンドです。雲上リソースの作成・変更・削除は行いません。移動後、構成(HCL)のアドレスと状態のアドレスが一致すれば、plan は差分なしになります。

バックエンドがリモートの場合も、対応していればロックを取得しつつ状態を直接更新します。ワークスペース間やバックエンド間の移動は直接は扱えません。

• 形式: terraform state mv [options] SOURCE DESTINATION
• 対象: リソースインスタンス(aws_instance.example、module.net.aws_vpc.main など)
• 動作: 状態のみを書き換える。API 呼び出しなし
• 安全性: plan で差分ゼロを確認してから apply
• ロック: 対応バックエンド(S3+DynamoDB など)ではロック取得

アドレス指定と代表的な移動パターン

Terraform のアドレスは、resource タイプ/名前、モジュール階層、count/for_each のインデックスで構成されます。state mv はこれらの「アドレスの変更」を安全に追従させるために使います。

代表パターンは次のとおりです。1) リソース名の変更、2) ルートからモジュールへ移動、3) count から for_each への再設計(インデックスとキーの対応付けを個別に移動)。

• リソース名変更: aws_instance.web → aws_instance.app
• モジュール化: aws_security_group.sg → module.network.aws_security_group.sg
• count→for_each: aws_instance.example[0] → aws_instance.example["a"]
• for_each のキー変更: aws_iam_role.role["old"] → aws_iam_role.role["new"]
• データソースの移動は原則稀。必要時のみ慎重に実施

ルートからモジュールへの移動イメージ

Before (state)
  aws_security_group.sg
       |
       v
After (state)
  module.network.aws_security_group.sg

構成(HCL)
  - 以前: resource "aws_security_group" "sg" { ... }
  + 以後: module "network" { source = "./modules/network" }
          # module 内に aws_security_group.sg を定義

安全な手順とロールバック戦略

実務では、移動前にバックアップを取り、plan で差分ゼロを確認し、問題時に即時戻せる準備をします。リモートバックエンドではロックを前提に短時間で完了させます。

部分的な移動を残したまま apply しないこと。構成と状態の対応が崩れると意図せぬ再作成が発生します。

• 事前に terraform fmt/validate/plan で構成の健全性を確認
• 状態のバックアップ: terraform state pull > backup.tfstate
• 移動→plan で差分ゼロを確認→コミット
• 異常時は backup.tfstate を push して即時復元
• チーム運用ではメンテナンスウィンドウ確保とロック確認

最小手順の例(リネームとモジュール化を順に検証)

# 状態のバックアップ
terraform state pull > backup.tfstate

# リソース名の変更
terraform state mv aws_instance.web aws_instance.app
terraform plan  # 差分なしであること

# モジュール化に伴う移動
terraform state mv aws_security_group.sg module.network.aws_security_group.sg
terraform plan  # 差分なしであること

# 問題があればロールバック例
# 1) ローカルに退避した backup.tfstate を確認
# 2) リモートでなければ: terraform state push backup.tfstate
#    リモートの場合は同等の復旧手順をチーム手順書に従って実施

moved ブロックとの違いと使い分け

Terraform 1.1+ には構成側でリネームを宣言できる moved ブロックがあります。moved は plan/apply 時に状態を自動で移す仕組みで、チームでの段階的移行や CI に馴染みます。一方、state mv は即時に状態を書き換える管理者ツールです。

設計判断として、安定したリネームやモジュール化は moved を優先し、緊急の修復やピンポイントなインスタンス単位の調整は state mv を使うのが実務的です。

• moved は構成に履歴を残せるため再現性が高い
• state mv は一撃で状態を直せるが、履歴は VCS のコミットメッセージ等で補う
• 大規模変更は moved で段階的、細粒度の個別調整は state mv

複雑ケースの取り扱い(count/for_each 他)

count → for_each 移行では、インデックスからキーへのマッピングを1件ずつ移します。計画的に順序を決め、各移動の後に plan で差分ゼロを確認します。

ワークスペース間やバックエンド間の直接移動は非対応です。必要なら import と state rm の併用、あるいは pull/push を使った慎重な手動移送を検討します(競合・ロックに要注意)。

• 例: terraform state mv aws_instance.example[0] aws_instance.example["a"]
• キー決定: 安定キー(名前やID)を選び、以後不変を前提にする
• module 間の移動は完全修了まで apply しない
• data ブロックの移動は原則不要。状態最適化の観点でのみ実施
• Workspace 跨ぎは直接不可。誤操作は破壊的になり得る

試験対策ポイントと実務チェックリスト

試験(プロフェッショナル相当)では、state mv の作用範囲、構成変更との関係、moved との比較、count/for_each・モジュール階層でのアドレス表記が問われやすいです。

実務では、バックアップ・ロック・段階適用・レビュー体制の4点を揃えると事故率を大きく下げられます。

• state mv は状態のみ変更。API 呼び出しなし
• 移動後に plan が差分ゼロなら成功
• module.<name>.resource.type.name のフルアドレスを正確に指定
• moved は宣言的・再現性重視、state mv は即時・手動調整向き
• 部分移行のまま apply しない。常に一貫性を保つ

問題で確認

よくある質問