Terraformリファクタリング手法: moved / removed / import の実務パターン

既存のリソースを壊さずに構成を整理するには、状態の整合性を保つための道具立てが不可欠です。本稿では Terraform の moved・removed・import を軸に、壊さないリファクタリングを段取り良く進める手法をまとめます。

HashiCorp 公式の安定機能を前提に、試験で狙われやすいポイントと現場での落とし穴を一体で押さえます。バージョン依存がある箇所は注意書きを付けています。

なぜ moved / removed / import なのか

Terraform は構成(コード)と状態(state)を突き合わせて差分を適用します。リファクタリング時にアドレス変更や撤去・取り込みがあると、状態の写像が崩れて誤消去や再作成が発生しがちです。moved・removed・import はこの『写像の修復』を公式に支援します。

特に、moved はアドレスの付け替え、removed は撤去の明示、import は既存資産の取り込みに対応します。正しく使えば計画はノーチェンジまたは最小差分になり、メンテナンスの安全性が飛躍的に上がります。

• 状態の写像を壊さない原則: 先に写像を直し、後でコードを動かす
• 計画(plan)は常に人が読む: 無関係な再作成が出たら中断
• 試験では各機能の『状態への作用』『実インフラへの作用』の違いが頻出

状態の写像を直してから適用する流れ

Before                Mapping                 After
aws_s3_bucket.web  -> moved{from web to app} -> aws_s3_bucket.app
(not imported)     -> import{id=...}         -> state has instance
(legacy)           -> removed/from           -> state forgets legacy

最小例: moved/removed/import を段取りに組み込む

# moved: リネームを安全に
moved {
  from = aws_s3_bucket.web
  to   = aws_s3_bucket.app
}

# removed: 撤去を明示 (サポート外/古い環境では state rm を使用)
# removed {
#   from = aws_s3_bucket.legacy
# }
# 代替: terraform state rm aws_s3_bucket.legacy  # 実体は削除しない

# import (Terraform 1.5+): 既存を取り込む
import {
  to = aws_s3_bucket.logs
  id = "my-logs-bucket"
}

moved ブロックの基本と定番パターン

moved ブロックは、リソースやモジュールのアドレスを変更した事実を Terraform に宣言します。これにより、状態の対応関係が保たれ、不要な destroy/create を避けられます。

よくあるのはリソース名のリネーム、モジュール階層の変更、for_each のキー変更です。いずれも『変更前の完全修飾アドレス』から『変更後の完全修飾アドレス』を正しく記述するのがコツです。

• 配置場所: 変更を行うモジュール側のルートに置く(そのモジュール配下に効く)
• 順序: 複数の moved は依存の浅いものから適用
• for_each/ count の個別インスタンスは [key] / [index] を明示
• モジュール跨ぎの移動は module.old.resource → module.new.resource の形で書く

moved によるアドレス再マッピング

State (old)                  Mapping                        State (new)
module.web.aws_lb.app  --->  moved{from module.web...        module.edge.aws_lb.app
                               to   module.edge...}
resource.srv["a"]      --->  moved{from srv["a"] to srv["blue"]}  resource.srv["blue"]

moved の書き方いろいろ

# 1) 単純リネーム
moved {
  from = aws_s3_bucket.web
  to   = aws_s3_bucket.app
}

# 2) モジュール間の移動
moved {
  from = module.old.aws_security_group.sg
  to   = module.new.aws_security_group.sg
}

# 3) for_each のキー変更
moved {
  from = aws_instance.srv["a"]
  to   = aws_instance.srv["blue"]
}

# 実務Tip: moved を追加→plan でノーチェンジを確認→その後にリネーム/移動のコード編集をコミット

removed の安全撤去パターン（および state rm 併用）

不要になったリソースを撤去する際は、状態と実インフラ双方で『何を残し、何を消すか』をコントロールします。Terraform では撤去の明示に removed を使える場合があります。環境やバージョンで未対応の場合は terraform state rm で状態から切り離すのが代替です。

重要なのは、state rm は状態からの除去のみで、実インフラは削除しない点です。逆に、構成からリソースを消すだけだと『destroy 計画』が出ます。どちらを選ぶかは運用方針(実体を残す/消す)で決めます。

• 実体を残す: state rm で Terraform の管理対象から外す
• 実体も消す: 構成を残したまま destroy させる(タグ付け等で最終確認)
• 順序を明記した PR と Release Note を用意し、適用タイミングを分ける
• バージョン差異に注意: removed ブロックが使えない場合の代替手順を準備

撤去時の分岐

Config remove?   State action         Infra action
Yes              plan shows -destroy  Destroy on apply
No (state rm)    state forgets        Infra remains
removed block    state forgets (decl) Infra: per plan/policy

撤去の具体手順

# A) 実体も削除: 計画で -destroy を確認してから適用
# (構成は一旦残す)
resource "aws_s3_bucket" "tmp" { /* ... */ }
# → plan に -/+ が出たら中断。- のみ(削除)を確認。

# B) 実体は残し管理解除: state rm
# 実体を別チームへ引き渡す等
terraform state list | grep aws_s3_bucket.tmp
terraform state rm aws_s3_bucket.tmp

# C) 宣言的撤去 (環境が対応している場合)
# removed {
#   from = aws_s3_bucket.legacy
# }

import ブロックによる宣言的インポート

Terraform 1.5+ では import ブロックで『どの実体(ID)をどのアドレスに取り込むか』を宣言できます。構成が実体の属性と一致すれば、計画はノーチェンジになり、既存資産の取り込みが安全に行えます。従来の terraform import CLI も利用可能です。

インポートに必要な ID は各リソースの公式ドキュメントに記載があります。複合 ID のケース(例: arn, project/region/name 形式)では正しいフォーマットで指定してください。

• import ブロックは一時的に追加し、取り込み後に残しておいても無害
• 構成と実体が一致しないと plan に差分が出る(原因切り分けの助け)
• 複数インスタンスは複数の import ブロックで列挙
• CLI import は即時だが宣言が残らないため、履歴性はブロックが優位

宣言的インポートの流れ

Existing Infra ----id----> import { to=addr, id=... } ----> State
                          ^ attributes must match resource config

import ブロックと CLI の併用例

# 1) 宣言的インポート (推奨: 1.5+)
resource "aws_s3_bucket" "logs" {
  bucket = "my-logs-bucket"
  force_destroy = false
}
import {
  to = aws_s3_bucket.logs
  id = "my-logs-bucket"
}

# 2) 旧来の CLI でも可
# terraform import aws_s3_bucket.logs my-logs-bucket

モジュール分割・統合での合わせ技（moved × import）

既存モノリシックモジュールの分割や、逆に統合するケースでは、moved でアドレスを付け替えつつ、外部に既存だったリソースは import で取り込みます。段階的に進めると計画の安定性が上がります。

推奨は『段階的リリース』です。1) 新モジュールを空で導入、2) moved で状態の写像を準備、3) 構成を移す、4) 足りない実体は import、5) テスト、という順。

• 写像の準備(moved)→構成移動→不足分の import の順を守る
• 分割時は module.path の完全表記で moved を網羅
• テスト環境で plan のノーチェンジを確認し、段階適用
• 統合時は命名衝突を先に解消(プレフィックスなど)

分割の段階適用イメージ

module.monolith.aws_*  --moved-->  module.network.aws_* / module.app.aws_*
        ^                                   ^ import missing pieces here
        |                                   |
     initial                          after staged refactor

モジュール分割のスケルトン

# 旧: module.monolith 内の SG を新: module.network へ
moved {
  from = module.monolith.aws_security_group.web
  to   = module.network.aws_security_group.web
}

module "network" {
  source = "./modules/network"
  # ... vars
}

# 取りこぼしの既存実体をインポート
import {
  to = module.network.aws_network_acl.default
  id = "acl-123456"
}

ガードレールとCI運用: 壊さないための手順化

リファクタリングは『手順の再現性』が品質です。計画の保存、レビュー、適用の分離、状態バックアップは定型にしましょう。特に moved/import を含む PR は、plan のノーチェンジ(または最小差分)をスクリーンショットやアーティファクトで必ず共有します。

ドリフトが疑われる場合は、適用前に状態の健全性チェック(state list/show)と、必要なら refresh を実行します。ターゲット適用(-target)は救済策であり恒常運用には使いません。

• terraform fmt/validate → plan -out=plan.tfplan → 人手レビュー → apply plan.tfplan
• state のバックアップを有効化(リモートバックエンド + バージョニング)
• 重要変更は環境で段階適用(dev → staging → prod)
• 失敗時のロールバック戦略(前バージョン state の復元)を準備

CI パイプラインの最小構成

[fmt] -> [validate] -> [plan -out] -> [manual review] -> [apply plan] -> [post-check]
   |                                                        ^ artifacts(plan, logs)

CI 実行例(擬似コード)

terraform fmt -check
terraform validate
terraform init -input=false
terraform plan -input=false -out=plan.tfplan
# 人手承認後
terraform apply -input=false plan.tfplan
# 監査用に state バックアップ/plan 出力を保存

問題で確認

よくある質問