Terraform refreshの現在地: 現状同期と代替コマンドを正しく使い分ける

Terraformでは、実環境とTerraform状態ファイルのズレを解消する「現状同期」が重要です。従来はterraform refreshを使っていましたが、現在は-refresh-onlyフラグを使うワークフローが推奨されています。

本稿では、公式の推奨に沿って現状同期の正しい実行方法、ハマりどころ、試験（Associate / Pro）で問われやすい観点を実務目線で整理します。

refreshの役割と「現状同期」の基本

Terraformはtfstateに「最後に把握した実リソースの状態」を保持します。人手変更や外部ツールにより実環境が変わると、状態ファイルとのズレ（ドリフト）が発生します。現状同期は、こうしたドリフトを実環境の事実で上書きして、状態ファイルを正す操作です。

従来のterraform refreshは、プロバイダ経由で実リソースを読み取り、状態ファイルだけを更新します。構成（.tf）は変更せず、インフラ自体も作成・更新・削除しません。現在は非推奨であり、後述の-refresh-onlyフラグを使うのが推奨です。

• 現状同期は「読み取り専用」であり、インフラに書き込みは行わない
• plan/applyはデフォルトで事前に状態の読み取り（リフレッシュ）を実施する
• refresh実行の副作用として「実在しないリソース」はstateから消える可能性がある

非推奨になったterraform refreshと代替コマンド

公式ドキュメントでは、従来のterraform refreshは非推奨扱いです。代替として、terraform plan -refresh-onlyとterraform apply -refresh-onlyが提供されています。これらは「状態のみを最新化する計画・適用」を明示でき、現在の推奨運用です。

バージョンにより細かな挙動メッセージや非推奨警告の出方は異なり得るため、実環境ではterraform versionやterraform -helpで手元のCLI仕様を常に確認してください。

• terraform plan -refresh-only: 状態を最新化する差分を可視化（実行はしない）
• terraform apply -refresh-only: 上記の差分をtfstateへ反映（インフラは変更しない）
• terraform plan -refresh=false: 計画時のリフレッシュを抑止し、API呼び出しや時間を節約

代替コマンドの最小セット

terraform plan -refresh-only
terraform apply -refresh-only

# 一部リソースだけ同期したいとき（必要最小限に）
terraform plan  -refresh-only -target=aws_instance.web
terraform apply -refresh-only -target=aws_instance.web

# 計画時にAPI読み取りを抑止（キャッシュ的に使う）。最終適用前には通常のplan/applyで検証を
terraform plan -refresh=false

ドリフト検出の実行フロー

Terraformの計画エンジンは、まずプロバイダ経由で実リソースの最新値を取得し、状態ファイルを前提に差分を計算します。-refresh-onlyを付けると、その差分は「状態ファイルの更新」に限定され、インフラに対する作成・変更・削除は提案されません。

図は、ユーザ操作からプロバイダ読み取り、状態の更新に至る経路を簡略化したものです。

• リフレッシュはプロバイダのRead操作を集中的に行うため、API制限やクォータに注意
• バックエンドがロック対応なら、同期中はロックが取得される（並行applyの競合を防ぐ）

現状同期（refresh-only）の高レベルフロー

User CLI
   |
   v
Terraform Core -----> State Backend (lock)
   |
   v
Provider(s) -----> Cloud/API (Read only)
   |
   v
Diff Engine (refresh-only: state updates only)
   |
   v
Update tfstate (no infra changes)

計画を保存してから安全に適用（状態のみ更新）

terraform plan -refresh-only -out=refresh.plan
# 差分をレビュー
terraform show refresh.plan
# 状態のみ更新を適用
terraform apply refresh.plan

実務での使い分けと注意点

監査・棚卸しや、手動変更の有無を把握したい場合は、まずterraform plan -refresh-onlyで可視化します。問題なければterraform apply -refresh-onlyでtfstateを最新化します。これはCIでの定期ドリフト検知や、障害対応後の事後同期にも有用です。

注意点として、実体が消えているリソースはrefresh-only適用でstateから削除されます。復旧の見込みがある、または意図せず消えた場合は、すぐにapply -refresh-onlyを行わず、原因究明やterraform importによる再取り込みを検討してください。

• まず-plan、からの-applyという二段階で安全に進める
• -targetは最小限の範囲に限定（恒常的な依存崩しに使わない）
• 大規模環境では-providersのAPI制限・レートを考慮し、スケジュールや並列度を調整
• バックエンドのロックが有効かを確認し、並行実行を避ける

削除済みリソースをstateから外したくない場合の選択肢

# すぐに適用しない。まず差分だけ確認
terraform plan -refresh-only

# 誤削除の可能性があるなら、復旧後にimportでstateに再取り込み
terraform import aws_instance.web i-0123456789abcdef0

コマンド比較と挙動の違い

似た名称でも目的と副作用が異なります。試験・実務の双方で混同しやすい点を整理します。

• インフラを変えないのはrefreshと-refresh-only系のみ
• デフォルトのplan/applyは事前リフレッシュを行う（-refresh=falseで抑止可能）

試験対策ポイント（Associate / Pro）

Associateでは、現状同期の意図と-refresh-onlyの意味合いを正しく選択できることが重要です。Proでは、ドリフトの扱い、-targetの限定使用、-refresh=falseの意図的な活用など、状況に応じたワークフロー設計が問われます。

覚えておくべきは、状態の最新化は通常plan/applyでも実施されるが、refresh-onlyは「状態更新に限定」する点です。インフラは決して変更されません。

• refreshは非推奨。正解はapply/planの-refresh-only
• 実体が無いと判定されたリソースは、refresh-only適用でstateから削除され得る
• -targetは緊急回避や範囲限定用途。常用は非推奨
• バックエンドのロックと並行実行の安全性にも言及できるとなお良い

問題で確認

よくある質問