terraform init 実務と試験に効く: backend・provider の初期化を正しく設計する

terraform init は、作業ディレクトリの初期化・backend（状態の保存先）・provider（クラウド SDK 相当）・モジュールの取得・依存ロックの作成を一括で行うコマンドです。

Associate 試験では、backend の再設定や state 移行時のフラグ、provider バージョン制約とロックファイルの扱いが頻出です。実務でも安全な初期化と再初期化の設計が欠かせません。

terraform init の役割と全体フロー

terraform init は main.tf などの設定を読み、必要な provider とモジュールを解決・取得し、backend を初期化します。初期化結果は .terraform ディレクトリと .terraform.lock.hcl（依存ロック）に反映されます。

実行フェーズは大きく「provider 解決」「module 取得」「backend 初期化」「ロックファイルの生成/更新」に分かれます。アップグレード時は -upgrade、backend を作り直すときは -reconfigure、state を移すときは -migrate-state を使います。

• 初回 clone 直後・provider/モジュール/backend を変更したときに実行する。
• .terraform.lock.hcl は選定した provider バイナリのハッシュを固定。原則 VCS にコミットする（再現性の担保）。
• -upgrade は許容範囲内で最新版に上げる。制約は required_providers の version でコントロール。
• -reconfigure は既存 backend 設定を無視して再初期化。対話なく移行するなら -input=false を併用。

init の俯瞰フロー

[main.tf] --parse--> (terraform init)
                      |---> [.terraform/providers]
                      |---> [.terraform/modules]
                      |---> [.terraform.lock.hcl]
                      \---> [Backend handshake + lock]

最小構成の初期化例（ローカル backend）

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
  backend "local" {}
}

provider "aws" {
  region = var.region
}

variable "region" {
  type    = string
  default = "ap-northeast-1"
}

# 実行
# terraform init

Backend 初期化: local から S3/azurerm/gcs まで

backend は Terraform の状態ファイル（tfstate）の保存先を定義します。チーム運用ではローカルではなくリモート backend（例: S3、AzureRM、GCS）が基本です。S3 は DynamoDB を用いたロックが一般的、AzureRM は Blob のリース、GCS は世代管理を使った競合防止を行います（実装は各 backend 固有）。

既存環境で backend を切り替える場合、-reconfigure で再初期化、既存 state を安全に移すには -migrate-state を併用します。資格情報や機密は backend ブロックに直書きせず、-backend-config か環境変数で与えます。

• S3 + DynamoDB ロックはチーム並行実行の基本パターン。
• -backend-config は key=value 複数指定や HCL ファイル指定（-backend-config=path）どちらも可能。
• backend の再設定時に -migrate-state を忘れると state が分断されるリスク。
• CI では -input=false で非対話実行にする。

S3 backend とロックの関係

[Terraform CLI] --read/write--> [S3: tfstate]
         |                          \
         |---lock/unlock-----------> [DynamoDB: lock item]
         |
         \---credentials-----------> [IAM/環境変数/プロファイル]

S3 backend 構成と安全な再初期化

# main.tf（資格情報は直書きしない）
terraform {
  backend "s3" {}
}

# backend.hcl（例）
bucket         = "my-tf-state"
key            = "app/terraform.tfstate"
region         = "ap-northeast-1"
dynamodb_table = "tf-lock"
encrypt        = true

# 既存 local から S3 へ安全に移行（非対話）
terraform init \
  -reconfigure \
  -migrate-state \
  -input=false \
  -backend-config=backend.hcl

Provider の初期化とバージョン固定

provider は各プラットフォームの API クライアントです。terraform init は required_providers に基づき、Terraform Registry 等から適切なバイナリを取得し .terraform/providers に配置、ハッシュを .terraform.lock.hcl に記録します。

バージョン制約は実務・試験ともに重要です。~> 演算子で互換の範囲を指定、メジャー更新を避けつつマイナー/パッチを追従します。CI では TF_PLUGIN_CACHE_DIR を使いダウンロードを削減します。

• required_providers の source は registry.terraform.io/<namespace>/<name> が既定。
• .terraform.lock.hcl は OS/CPU ごとのハッシュを保持。複数プラットフォームで使う場合は事前にロック生成（providers lock）。
• -upgrade は制約内の最新版選定をやり直す。再現性を崩さないよう PR で差分確認。

Provider 取得とキャッシュ

[Terraform CLI] --resolve--> [Terraform Registry]
        |                          |
        |--download--> [$HOME/.terraform.d/plugin-cache] (任意)
        |                          |
        \------deploy-------------> [.terraform/providers]
                                   \-> [.terraform.lock.hcl]

Provider 固定とキャッシュの設定例

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.6"
    }
  }
}

provider "aws" {
  region = var.region
}

# ダウンロードキャッシュ（シェル環境）
export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache"
mkdir -p "$TF_PLUGIN_CACHE_DIR"

# 初期化（制約内で最新版へ）
terraform init -upgrade

環境ごとの初期化戦略: -backend-config と再現性の担保

同一コードを dev/stg/prod で使い回す場合、backend 設定と資格情報を環境別ファイルに分離し、-backend-config で注入します。再初期化が必要な変更では -reconfigure、state 保存先を変えるときは -migrate-state を必ず併用します。

CI 実行では -input=false で非対話化し、-lockfile=readonly でロックファイルの予期せぬ更新を防ぎます。

• backend-<env>.hcl で保存先やロックテーブルを分離。
• 資格情報は環境変数や Vault/OIDC で払い出し、コード非掲載を徹底。
• provider は同一バージョンで固定し、環境差は入力変数で吸収。

1 つのコードを複数環境で初期化

[repo]
  |-- main.tf
  |-- backend-dev.hcl
  |-- backend-stg.hcl
  |-- backend-prd.hcl

[CLI] --dev--> terraform init -backend-config=backend-dev.hcl
[CLI] --stg--> terraform init -backend-config=backend-stg.hcl
[CLI] --prd--> terraform init -backend-config=backend-prd.hcl

環境別 backend と CI 向け init コマンド

# backend-stg.hcl
bucket         = "my-tf-state-stg"
key            = "app/terraform.tfstate"
region         = "ap-northeast-1"
dynamodb_table = "tf-lock-stg"

# backend-prd.hcl
bucket         = "my-tf-state-prd"
key            = "app/terraform.tfstate"
region         = "ap-northeast-1"
dynamodb_table = "tf-lock-prd"

# ステージングを初期化（ロックファイルは読み取り専用）
terraform init \
  -backend-config=backend-stg.hcl \
  -input=false \
  -lockfile=readonly

# 本番へ backend 切替と state 移行（CI）
terraform init \
  -reconfigure \
  -migrate-state \
  -backend-config=backend-prd.hcl \
  -input=false \
  -lockfile=readonly

トラブルシューティングと試験で狙われるポイント

backend 再設定時の -migrate-state 抜け、provider バージョン不一致、ネットワーク制限下のダウンロード失敗は定番です。メッセージを鵜呑みにせず、.terraform ディレクトリ、.terraform.lock.hcl、backend 設定の三点を確認します。

Associate では、どのフラグを使えば安全に初期化/再初期化できるか、ロックファイルの扱い、資格情報の安全な注入方法が問われやすいです。

• backend 変更時は -reconfigure と -migrate-state のセットを意識。
• provider の急な解決失敗は -upgrade かロックファイル差分の確認。
• ネットワーク遮断環境は TF_PLUGIN_CACHE_DIR とミラー/プロキシで回避。

よくある失敗パターン（backend 移行忘れ）

[local backend] --(state 残存)--> [開発者PC]
         \
          X  terraform init（-migrate-state なし）
           \
            --> [S3 backend]  --結果: state が分断/競合

復旧・検証によく使うコマンド

# backend 再交渉 + state 安全移行
terraform init -reconfigure -migrate-state -backend-config=backend.hcl -input=false

# provider を制約内で再選定
terraform init -upgrade

# 異種プラットフォーム向けにロック事前生成（複数 OS/CPU）
terraform providers lock -platform=linux_amd64 -platform=darwin_amd64

# どうしても壊れたときの最終手段（要注意）
# rm -rf .terraform && terraform init

問題で確認

よくある質問