Terraform トラブルシューティング: よくあるエラーと原因

Terraform は CLI、プロバイダ、バックエンド、状態ファイルの4点が噛み合って動きます。エラーはこのどこかの前提が崩れたときに出ます。本稿はエラーの型を素早く見極め、再現性を保ったうえで最短の修復手順に導くことを目的にしています。

資格対策としては、エラーメッセージの読み方、required_providers と .terraform.lock.hcl、S3+DynamoDB ロック、バックエンド再初期化、認証連鎖の基本を問う出題が多いです。試験では危険な回避策を選ばない判断も重視されます。

まず押さえる初動とデバッグの基本

トラブル時は、原因特定前に環境差異とキャッシュの影響を最小化します。作業前に Terraform/プロバイダのバージョン、バックエンド設定、認証状態を確認し、初期化をやり直すだけで直るケースは多いです。

試験観点では、TF_LOG と TF_LOG_PATH の使い方、terraform init の -reconfigure と -upgrade の違い、plan -refresh-only による状態アクセスの切り分けが頻出です。

• バージョン確認: terraform version と terraform providers
• 初期化やり直し: terraform init -reconfigure （バックエンド設定変更時）、必要なら -upgrade
• 構文チェック: terraform validate（構文/内部参照の早期発見）
• 状態アクセスだけ切り分け: terraform plan -refresh-only
• ログ: export TF_LOG=INFO 〜 TRACE、export TF_LOG_PATH=./terraform.log
• 無関係な色や対話を抑止: -no-color、-input=false

初動で安全に実施する最小コマンド

# バージョン/依存の可視化
terraform version
terraform providers

# バックエンドやプロバイダを健全化
terraform init -reconfigure
# 必要に応じてプロバイダ更新
# terraform init -upgrade

# ログ出力（詳細化は必要時のみ）
export TF_LOG=INFO
export TF_LOG_PATH=./terraform.log

# 状態アクセスだけ検証
terraform plan -refresh-only -no-color -input=false

プロバイダ認証エラーの切り分け

多くの失敗は認証連鎖の前提崩れです。Terraform の多くのプロバイダは環境変数、共有クレデンシャルファイル、CLI ログイン、明示設定の順で資格情報を探索します。実行ユーザや CI 環境で探索順が変わらないよう固定しましょう。

典型として AWS NoCredentialProviders、GCP ADC 未設定、AzureRM でサブスクリプション権限不足があります。試験では、プロファイルやサービスプリンシパルの使い分け、短期トークンの期限切れを特定できるかが問われます。

• AWS: AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN、~/.aws/credentials、profile 指定、AssumeRole の期限切れ
• GCP: GOOGLE_APPLICATION_CREDENTIALS による ADC、gcloud auth application-default login、プロジェクト誤り
• AzureRM: az login または ARM_CLIENT_ID/ARM_TENANT_ID/ARM_SUBSCRIPTION_ID/ARM_CLIENT_SECRET、MSI 使用時は managed identity の割当確認
• ローカルと CI の探索順不一致を避けるため、provider ブロックで profile や subscription を明示

代表的な provider 設定例（明示的に固定してブレを無くす）

# AWS
provider "aws" {
  region  = var.aws_region
  profile = var.aws_profile  # CI では環境変数に合わせて固定
}

# Google
provider "google" {
  project = var.gcp_project
  region  = var.gcp_region
  # 環境変数 GOOGLE_APPLICATION_CREDENTIALS でサービスアカウント JSON を渡す
}

# AzureRM
provider "azurerm" {
  features {}
  # az login もしくは ARM_* 環境変数で固定
}

ステートロックと並行実行の問題

S3 バックエンドに DynamoDB ロックを併用するなど、Terraform は通常ステートに対する排他制御を行います。異常終了や二重実行でロックが残ると、Error acquiring the state lock が発生します。まずは本当に別プロセスが走っていないか確認して待機します。

ロックが孤立している確証がある場合のみ force-unlock を使います。DynamoDB のロック項目を手作業で削除するのは推奨されません。Terraform CLI のエラーメッセージに表示される LockID を指定するのが安全です。

• CI の並行キューを止める、ローカルの残存 terraform 子プロセスを終了
• DynamoDB への Query 権限不足でもロック失敗に見えるので IAM を確認
• 別バージョンの Terraform が同じステートを読むと互換性エラーが出ることがあるため、CLI のバージョンを合わせる

S3 バックエンド + DynamoDB ロックの流れ

ロック解除と再試行の定石

# エラーに表示された LockID を使用（例）
terraform force-unlock 12345678-90ab-cdef-1234-567890abcdef
# 自動確認を省略する場合は -force を付与
# terraform force-unlock -force 12345678-90ab-cdef-1234-567890abcdef

# 直後に並行実行がいないことを確認して再実行
terraform init -reconfigure
terraform plan -refresh-only

Terraform 本体・プロバイダのバージョン不整合

required_version と required_providers、そして .terraform.lock.hcl の3点が噛み合っていないと、Incompatible provider version や state created by newer Terraform が発生します。チームで CLI とプロバイダのバージョン帯を揃えましょう。

プロバイダ更新は terraform init -upgrade で行い、想定外の更新を避けたい場合は制約を厳密化します。エアギャップ環境では providers mirror でレジストリに頼らない配布も可能です。

• terraform ブロックで required_version と required_providers に上限下限を明示
• ロックファイル .terraform.lock.hcl はコミットして再現性を確保
• state created by newer Terraform が出たら、CLI をそのバージョン以上に更新するのが基本解
• registry アドレスは namespace/type 形式に正しく指定（旧形式からの移行エラーに注意）

バージョン制約の例

terraform {
  required_version = ">= 1.4, < 2.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"   # マイナー範囲に固定して予期せぬ破壊的変更を回避
    }
    google = {
      source  = "hashicorp/google"
      version = ">= 4.0, < 6.0"
    }
  }
}

# 更新が必要なときだけ明示
# terraform init -upgrade

依存関係エラーと強制置換の読み解き

Cycle: ... depends on ... は循環参照があるサインです。data ソースで分離する、depends_on を減らす、モジュール境界を見直すのが定石です。

forces replacement は属性変更が破壊的でアトリビュートの差分によりリソース再作成が必要な状態です。影響範囲を小さく検証するには -replace を使い、lifecycle で create_before_destroy や prevent_destroy を設けると安全性が上がります。

• for_each や count のキーが不安定だと destroy → create の順序問題を生むので、安定キーを採用
• Invalid for_each argument は null や重複キーが原因になりやすい
• replace を併用して一点差し替えの挙動を確かめる

安全な置換とライフサイクルの例

# 影響範囲を限定して検証
terraform plan -replace=aws_instance.web[0]

# 破壊的変更に備えた lifecycle
resource "aws_launch_template" "app" {
  name_prefix = "app-"
  # ...
  lifecycle {
    create_before_destroy = true
    prevent_destroy       = false
  }
}

バックエンドとワークスペースの落とし穴

Backend initialization required は backend 設定が変わったのに再初期化していないときに出ます。-reconfigure で現在の設定を優先して初期化し直してください。

Failed to get existing workspaces や AccessDenied は、バックエンドの一覧権限やワークスペース命名の不一致で起きます。S3 の ListBucket、DynamoDB の Query/Put、Terraform Cloud のトークン有効性を確認します。

• backend 設定を変えたら terraform init -reconfigure を必ず実行
• ワークスペースの存在確認と切替: terraform workspace list/select/new
• CLI 設定ファイル（~/.terraformrc または %APPDATA%/terraform.rc）で Terraform Cloud のトークン管理
• ローカルステートとリモートステートの混在を避ける（チームで統一）

代表的な backend 設定と再初期化

terraform {
  backend "s3" {
    bucket         = "example-tfstate"
    key            = "envs/prod/terraform.tfstate"
    region         = "ap-northeast-1"
    dynamodb_table = "tfstate-lock"
    encrypt        = true
  }
}

# 設定変更後
terraform init -reconfigure

# ワークスペース運用
terraform workspace list
terraform workspace select prod

問題で確認

よくある質問