TerraformのTF_LOGとデバッグ実践：詳細ログの取り方

Terraformで原因不明の失敗や差分の謎に直面したとき、TF_LOG系の環境変数で詳細ログを出すのが基本です。

ただしログ量は膨大になりがちで、設定や取り扱いを誤ると調査が長引いたり機密情報が漏れたりします。本稿では安全なログ取得手順、読み解きの勘所、試験で問われやすい論点を実務目線で整理します。

TF_LOGの基本とログレベル

Terraformは環境変数TF_LOGで詳細ログを有効化できます。値はTRACE, DEBUG, INFO, WARN, ERRORで、下位ほど冗長です。通常のトラブルシュートはDEBUG、深掘りが必要なときのみTRACEが目安です。ログは標準エラーに出力されますが、TF_LOG_PATHを使うとファイルに書き出せます。

より細かく制御したい場合は、TF_LOG_CORE（Terraformコア）とTF_LOG_PROVIDER（プロバイダ・プラグイン）を使います。未設定の部分はTF_LOGの設定が既定として適用され、個別に設定した方が優先されます。詳細ログにはAPIリクエストなどの断片が含まれることがあり、取り扱いには注意が必要です。

• ログレベルの目安: DEBUG=一般的な調査, TRACE=再現性の低い/深刻な不具合の掘り下げ
• 出力先: 既定は標準エラー、TF_LOG_PATHでファイル出力に切替
• スコープ: TF_LOG（全体）、TF_LOG_CORE（コアのみ）、TF_LOG_PROVIDER（プロバイダのみ）
• 注意: 機密情報が含まれる可能性。共有前に必ずマスクや削除

Terraform詳細ログの流れ（どこで何が出るか）

基本の有効化（Linux/macOS, Windows）

# Linux/macOS
export TF_LOG=DEBUG
export TF_LOG_PATH=./terraform-debug.log
terraform plan

# Windows (PowerShell)
$env:TF_LOG = "DEBUG"
$env:TF_LOG_PATH = "./terraform-debug.log"
terraform plan

# 終了後は無効化
unset TF_LOG TF_LOG_PATH  # PowerShell: Remove-Item Env:TF_LOG, Env:TF_LOG_PATH

最短で再現ログを取る：手順とコツ

まずは再現性のある最小ディレクトリでDEBUGレベルのログを取り、問題の切り分けを進めます。TRACEは最終手段で、必要箇所の直前に切り替えると読みやすさが保てます。

CI/CDではジョブごとにTF_LOG_PATHを分け、ログローテーションや保持期間を明確にします。カラー出力は-no-colorで抑制できます（ログの可読性向上）。

• 最小構成で再現 → DEBUGで取得 → 必要時のみTRACE
• TF_LOG_PATHでファイル保存し、標準出力と分離
• -no-colorで制御文字を抑制（CIなどで有効)
• 長時間のTRACEは避ける（性能・容量インパクト）

再現ログの標準手順（Bash例）

set -euo pipefail
export TF_LOG=DEBUG
export TF_LOG_PATH="./repro-$(date +%Y%m%d-%H%M%S).log"
terraform init -upgrade
terraform plan -no-color
# 問題がplanに出ない場合のみapply前に必要箇所だけTRACE
export TF_LOG=TRACE
terraform apply -refresh-only -no-color  # 影響を最小化して差分だけ確認
# 片付け
env -u TF_LOG -u TF_LOG_PATH true >/dev/null 2>&1 || true

DEBUG/TRACEログの読み解き方

ログは時系列で読み、まずエラー直前のWARN/ERRORを起点に周辺のDEBUG行を遡ると因果を特定しやすくなります。プロバイダ呼び出しはリソースアドレス（例：module.db.aws_db_instance.this）やRPC方向（request/response）の相関を手がかりにします。

差分が期待と異なる場合は、計画フェーズでのUnknown値の扱い（computed属性）や、読み込み後の正規化（plan後のrefresh/plan再実行）に注目します。冗長なTRACEはgrepで間引き、関心リソースの行だけ抽出して芯を追います。

• エラーの直前5〜20秒を重点確認
• 対象リソースアドレスをキーにgrepやビュー分割
• API呼び出しはrequest→responseの順で整合確認
• Unknown/Computed属性の流れを追う（計画→適用後）

ログの絞り込み例（grep/awk）

# リソースアドレスで絞り込み
grep -F "module.db.aws_db_instance.this" terraform-debug.log | less

# レベルと時刻で周辺を確認
awk '/ERROR|WARN|DEBUG/ {print}' terraform-debug.log | less

# request/responseの対を確認
grep -E "(request|response)" terraform-debug.log | grep aws_db_instance | less

プロバイダだけ詳しく：ノイズを抑えて深掘り

コアは落ち着いているが、API層で異常が疑われる場合はTF_LOG_PROVIDERだけDEBUG/TRACEに上げ、TF_LOG_COREはINFOまたはWARNに抑えるとノイズが減ります。これで差分計算の詳細は抑えつつ、HTTP相当のやり取りや属性反映の流れを重点的に追えます。

WindowsやCIでは一時的にスコープを切り替えて、問題箇所の直前と直後だけ高レベルにすることでログ肥大化を防げます。

• TF_LOG_PROVIDER=DEBUG/TRACE, TF_LOG_CORE=WARN/INFO
• 問題箇所の直前だけレベルを引き上げ、適用後に戻す
• CIではステップごとに環境変数を調整しログ分割

スコープ別ログ制御（PowerShellとBash）

# PowerShell
$env:TF_LOG_CORE = "WARN"
$env:TF_LOG_PROVIDER = "DEBUG"
$env:TF_LOG_PATH = "./provider-only.log"
terraform plan

# Bash
export TF_LOG_CORE=INFO
export TF_LOG_PROVIDER=TRACE
export TF_LOG_PATH=./provider-trace.log
terraform apply -refresh-only -no-color

典型トラブル別：どこをどう見るか

認証系エラー: コアは成功でもプロバイダのリクエストが拒否されるケースでは、プロバイダ側のDEBUG/TRACEに資格情報の検出、エンドポイント、スコープなどの手がかりが出ます。プロファイルや環境変数の解決順も併せて確認します。

差分が不安定: Data Sourceの読み込み順や、外部変更による漂流を疑い、refresh-onlyやplanの再実行で安定性を比較します。プロバイダの正規化ロジックが属性を丸めていないかも要確認です。

• 認証/権限 → プロバイダDEBUGでクレデンシャル検出とスコープ確認
• 漂流/外部変更 → refresh-onlyで現状吸い上げてから比較
• 属性正規化 → apply後の読み直しで差分解消の有無を確認
• 機密取り扱い → ログ共有前に必ず秘匿情報を再点検

安定性比較の最小手順（Bash）

export TF_LOG=DEBUG
export TF_LOG_PATH=./stability-compare.log
terraform plan -no-color
terraform apply -refresh-only -no-color
terraform plan -no-color
# 3ステップの差を比較して不安定箇所を特定

試験対策と運用の勘所

Associate/Pro試験では、TF_LOG/TF_LOG_CORE/TF_LOG_PROVIDER/TF_LOG_PATHの役割、ログレベルの意味、標準エラー出力である点、-no-colorとの併用などが頻出です。どれをいつ使うかを言語化できるようにしましょう。

Terraform Cloud/Enterpriseのリモート実行では、TF_LOGはローカルCLIの挙動にしか効きません。実行本体はリモート側のランログを参照します。CIではジョブ単位のファイル出力と保持期間、秘匿情報のマスキング手順を標準化します。

• 試験対策: 環境変数のスコープと優先関係を整理
• 実務: ログは標準エラー。TF_LOG_PATHでファイル化、ローテーションは自前
• リモート実行: 端末側TF_LOGは限定的。リモートのランログを確認

CIでの安全な取得（例: GitHub Actions ステップ抜粋）

- name: Terraform Plan (debug log)
  env:
    TF_LOG: DEBUG
    TF_LOG_PATH: terraform-${{ github.run_id }}.log
  run: |
    terraform init -input=false
    terraform plan -no-color -input=false
  # アーティファクトに保存し、機密文字列はマスクポリシで保護

問題で確認

よくある質問