Terraform ドリフト検出の実務設計：定期的な plan 実行で“意図しない差分”を見逃さない

本稿は、Terraform のドリフト検出を「定期的な plan 実行」で仕組み化するための実務指針です。変更を加えずに差分だけを検出し、失敗基準と通知を自動化することで、予期せぬ本番変更を防ぎます。

HashiCorp 公式ドキュメントで安定運用されている機能（plan のリフレッシュ段階、-detailed-exitcode、-refresh-only、リモートバックエンドのロック、Terraform Cloud のワークスペース実行・通知）を前提に、資格対策でも狙われやすい論点を含めて整理します。

ドリフト検出の前提と「定期 plan 実行」の狙い

ドリフトとは、Terraform のコードと state が意図する構成と、実インフラ（クラウド API 上の実体）が一致しない状態です。代表例は、手作業変更、他ツールによる更新、自動スケーリングやローテーションの副作用です。

定期的な plan 実行の目的は、インフラを変更せずに差分の有無を確認し、閾値（例: 差分検知＝パイプライン失敗）で通知することです。日次・時間単位のチェックにより、予兆段階で対処できます。

• 変更を加えない検出を原則化（plan のみ、apply しない）
• state と実体の差分・コードと実体の差分の双方を把握
• 検出の成否を機械可読な終了コードで扱い、通知に直結

plan の挙動と主要フラグ：-detailed-exitcode と -refresh-only

terraform plan は、事前にリフレッシュ段階で実インフラの状態を読み取り、state を最新化してから差分を評価します。これにより、手作業変更などの外部更新を把握できます。

-detailed-exitcode は、差分の有無を終了コードで返すための必須フラグです。パイプラインでの分岐（0=差分なし、2=差分あり）に使えます。-refresh-only は、実インフラに変更を加えず、state の更新提案だけを出す専用モードで、変更を行わない“ドリフト検出”に適しています。

• terraform plan -detailed-exitcode の終了コード: 0=差分なし、1=エラー、2=差分あり
• -refresh-only は“state を現実に合わせる提案のみ”を表示。リソースを変更する提案は出さない
• ドリフト検出に限定するなら、-refresh-only -detailed-exitcode の組み合わせが安全

OSS + CI/Cron で実装する「毎日 plan」

最小構成は、スケジューラ（例: GitHub Actions の schedule、Jenkins の cron）で定期的に terraform plan -refresh-only -detailed-exitcode を実行し、終了コード 2 を検出したら通知・チケット化する流れです。実行環境には読み取り権限の資格情報（必要に応じて読み取り＋記録の最小権限）を付与します。

バックエンドはリモート（例: Terraform Cloud/Enterprise、S3 + DynamoDB ロック）を使用し、ロックと一貫性を担保します。複数ワークスペースがある場合は並列度を調整し、API レート制限やコストを抑えます。

• 資格情報は短期クレデンシャルを推奨（OIDC・STS など）
• ワークスペース単位にジョブ分割し、失敗はその場で可視化
• 差分あり（Exit 2）＝検出成功として“失敗扱い”にし通知

定期 plan によるドリフト検出（概念図）

GitHub Actions（schedule）での -refresh-only ドリフト検出例

name: Drift Detection (Nightly)

on:
  schedule:
    - cron: '0 2 * * *'  # UTC 02:00
  workflow_dispatch:

jobs:
  plan-refresh-only:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # OIDC でクラウドにフェデレーション
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Set up Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: 1.x
      - name: Cloud credentials (example)
        run: |
          echo "短期クレデンシャルをここで取得（例: AWS STS / GCP Workload Identity）"
      - name: Terraform init (remote backend)
        run: terraform init -input=false
      - name: Drift detection (refresh-only)
        id: plan
        run: |
          set -e
          terraform plan -refresh-only -detailed-exitcode -no-color || RC=$?
          if [ "${RC}" = "2" ]; then
            echo "DRIFT=true" >> $GITHUB_OUTPUT
            exit 2
          elif [ -n "${RC}" ] && [ "${RC}" != "0" ]; then
            echo "Terraform error (RC=${RC})" >&2
            exit ${RC}
          fi
      - name: Notify on drift
        if: failure() && steps.plan.outputs.DRIFT == 'true'
        run: |
          echo "Drift detected. Post to Slack / create issue here."

Terraform Cloud/Enterprise を活用した検出・通知

Terraform Cloud/Enterprise のワークスペース実行を使うと、リモート状態管理・ロック・権限分離・通知チャネル連携を一体で扱えます。ドリフト検出（リフレッシュ起点の評価）やスケジュール/ポリシー連携を用いると、検出と可視化をプラットフォーム側に寄せられます（利用可否や詳細は公式ドキュメントの最新情報を参照してください）。

設計のポイントは、検出用実行と変更適用用実行を分離すること、通知チャネル（メール、Webhook 等）でのアラート運用を明確にすること、必要に応じてポリシー（Sentinel など）で“手動変更を検出したら適用をブロック”といったガードレールを敷くことです。

• ワークスペース単位での権限・変数・通知チャネル管理
• 検出専用の実行（適用なし）を前提に、運用上の誤 apply を予防
• 大規模環境では組織・プロジェクト・タグでの横断的な可視化を活用

運用の落とし穴とガードレール

資格情報は最小権限・短期化を徹底します。検出だけなら読み取り中心ですが、バックエンド種別によっては state 書き込みやロック取得が必要になるため、バックエンド要件に合わせた権限設計が必要です。

API レート制限と実行コスト対策として、並列度（-parallelism）、ワークスペースのバッチ分割、動的に変更頻度の高いスタックの優先度制御を行います。ノイズ低減には lifecycle の ignore_changes を適切に使い、可変要素（タイムスタンプやランダム値）を計画に載せない工夫が有効です。

• remote backend を使用しロックを有効化（整合性の担保）
• 出力のノイズ低減（-no-color、ログ要約、差分のみ通知）
• エラー（終了コード 1）とドリフト（終了コード 2）を区別して運用
• 変更多発リソースは ignore_changes や別ワークスペースへ分離

試験対策：問われやすい観点（Pro レベル）

plan の事前リフレッシュ、-detailed-exitcode の意味、-refresh-only と通常 plan の使い分けは基本問題として出題されやすいです。バックエンドのロック、ワークスペース設計、Sentinel/ポリシー連携、サービスアカウントの最小権限なども頻出です。

シナリオ問題では「定期的に差分だけを検出し、インフラは絶対に変更しない」「差分時は通知して手動レビューへ」という要件が提示されます。この場合は plan -refresh-only -detailed-exitcode を選び、終了コード 2 を通知トリガーにする、が模範解です。

• 0/1/2 の終了コード解釈を暗記
• -refresh-only は“検出専用”として安全に使える
• remote backend + ロック必須、並列度とレート制限の管理
• ワークスペース/変数/通知の分離と最小権限
• ノイズ対策（ignore_changes、差分のみ通知）

問題で確認

よくある質問