terraform planで変更差分を正確に読む（Associate向け・実務両対応）

terraform planは、状態と実際のリソース、そして現在の構成から導かれる“これからの変更”を可視化します。誤解しやすいのは、planはあくまでシミュレーションであり、適用（apply）しない限りインフラは変わらないことです。

この記事では、差分記号の正しい読み方、主要オプションの使いどころ、CI/CDでの自動判定、ドリフト検出のコツまで、試験（Associate）と実務の両軸で整理します。

terraform planの基本と差分記号の読み方

terraform planは、現在の状態（state）と実環境の読み取り（デフォルトでrefresh）を踏まえ、構成（HCL）から導かれる実行計画を出力します。出力は“何がどの順で、なぜ変わるのか”を示すため、レビューとリスク低減の中心的な道具になります。

差分出力では、+が作成、-が削除、~がインプレース更新、-/+や+/-が置換（再作成）を意味します。属性単位でも~が付きますが、リソース行頭が-/+の場合は破壊と再作成が必要な変更であることを示します。

• planは実際の変更を行わない。適用はterraform applyで行う。
• デフォルトでrefresh（実リソースの再読み取り）を行う。制御は-refreshフラグで可能。
• 出力の順序は依存関係に基づく。破壊→作成の順で安全性が考慮される。
• 保存した計画ファイル（-out）は、同一ワークスペース・同一設定でのみ有効。

planの位置づけ（構成→計画→適用）

最小手順と出力保存

terraform init
terraform plan -out=plan.tfplan
# レビュワーは plan.tfplan を
# terraform show plan.tfplan で確認可能

差分の精度を高める主要オプション

運用では、ドリフト検出や限定的な影響確認のためにオプションを使い分けます。-refresh=falseで外部の再読み取りを抑制すると、ネットワーク不安定時の暫定評価に役立ちますが、最新の実態を反映しないためリスクが上がります。

-refresh-onlyは、実リソースに変更を加えずにstateだけを最新化する計画を作ります。変更の適用はterraform apply -refresh-onlyで行われ、外形的には“差分ゼロ化（state同期）”の動きになります。

• -replace=アドレス で明示的な置換計画を作成できる（taintの代替）。
• -destroy で“破壊のみ”の計画を作成（最終撤去の安全確認に有用）。
• -var-file や -var は計画に使う入力値を固定化し、再現性を高める。

refresh-onlyのイメージ

代表的な組み合わせ例

# ドリフト確認を厳密に
terraform plan

# ネットワーク不調時の暫定差分確認（最終判断は避ける）
terraform plan -refresh=false

# stateを最新化するだけの計画
terraform plan -refresh-only

# 特定リソースの置換
terraform plan -replace=aws_instance.web

CI/CDでの自動判定と計画の共有

CIでは-detailed-exitcodeで差分の有無を機械判定します。0は差分なし、2は差分あり、1はエラーです。PRにplan出力をコメント化する運用も一般的です。

計画の再現性を高めるため、-outでバイナリ計画ファイルを生成し、terraform show -jsonで機械可読化します。計画ファイルはTerraformのバージョン・バックエンド・ワークスペースに依存するため、別環境への持ち回りは避けます。

• plan → レビュー → 承認 → apply の分離で権限最小化を実現。
• 保存済みplanをapplyすると承認プロンプトは表示されない（無人適用に適合）。
• JSON化により差分の可視化ダッシュボードを作成可能。

CIパイプラインの典型

Bash例: 差分ありのみ失敗させる

set -euo pipefail
terraform init
if terraform plan -detailed-exitcode -out=plan.tfplan; then
  echo "No changes"
else
  code=$?
  if [ "$code" -eq 2 ]; then
    echo "Changes detected" >&2
    terraform show -json plan.tfplan > plan.json
    exit 2
  else
    echo "Plan failed" >&2
    exit $code
  fi
fi

実務のパターンと落とし穴（ドリフト、インポート、未知値）

既存リソースが手作業で変更されている場合、planは~または-/+としてドリフトを示します。既存資産の取り込みはterraform importでstateに紐付けてから行うのが安全です。

データソースや未確定の値（apply時決定値）はplanでunknownとして扱われることがあります。unknownが置換要件を引き起こさないか、注意深く読みます。

• ドリフトの常時監視には、定期的なplan実行が有効。
• import前の構成は既存と一致させる（名前・タグ・重要属性）。
• unknownが多い場合は依存関係やlifecycleの設定を見直す。

ドリフト検出の流れ

インポートと最小差分の作り方

# 既存S3バケットをstateへ取り込み
# 事前にHCLを既存設定に合わせておく
terraform import aws_s3_bucket.logs my-existing-logs-bucket
terraform plan  # ドリフトが解消されていることを確認

Associate試験で問われやすい論点

planは提案であり、applyのみが変更を実行すること。-detailed-exitcodeの意味、-outで保存した計画をapplyすると承認なしで適用されることは頻出です。

-targetは恒常運用の推奨ではない、-destroyは破壊計画を作る、-refresh-onlyはstate同期のための計画を作る、といった“意図の違い”が問われます。

• exit code: 0=変更なし, 2=変更あり, 1=失敗。
• 保存計画の適用ではプロンプトが出ない（無人化できる）。
• planのJSONはterraform show -jsonで取得する（plan自体はJSON直接出力しない）。

試験での意思決定チャート（簡略）

試験頻出コマンドサマリ

# 差分の有無だけ知る
terraform plan -detailed-exitcode

# 破壊計画
terraform plan -destroy

# 保存→適用
terraform plan -out=plan.tfplan
terraform apply plan.tfplan

# JSONでレビュー
terraform show -json plan.tfplan > plan.json

トラブルシュート：置換・移動・ロック・権限

planで“forces replacement”が出たら、immutable属性が変わっていないか確認します。仕様上の再作成が必要な場合は、-replaceで明示的に意図を示すと安全です。

リソース名の変更やモジュール再編ではmovedブロックを使うと、destroy/createを避けてstateを自動移行できます。バックエンドのロック競合や認可エラーはplan以前の問題として検出されるため、まずは資格情報とロック状態を確認します。

• movedブロックで安全な改名。state mvの代替として推奨。
• バックエンドのロックは解放を待つ。強制解放は最終手段。
• プロバイダの権限不足はplanのrefresh段階で失敗しがち。

改名時のmovedブロック適用イメージ

movedブロックと置換の明示

# main.tf（Terraform 1.x系）
moved {
  from = aws_instance.old_name
  to   = aws_instance.new_name
}

# 不可避の再作成を明示
# terraform plan -replace=aws_instance.web

問題で確認

よくある質問