Terraform プロバイダのバージョン制約とロック実務

Terraform は required_providers のバージョン制約で「許容範囲」を宣言し、.terraform.lock.hcl で「実際に使う厳密なバージョン」を固定します。両者の役割を正しく分けると、CI での偶発的なアップグレードを防ぎつつ、計画的な更新が可能になります。

本稿では制約の書き方、ロックの更新タイミング、CI/チーム運用のコツ、エラー時の対処をまとめ、Associate 試験で問われがちなポイントを明確にします。

required_providers とロックの全体像

required_providers は「どのプロバイダを、どのソースから、どのバージョン範囲で許可するか」を宣言します。これはあくまで範囲指定であり、厳密な単一バージョンの固定ではありません。

.terraform.lock.hcl は terraform init 実行時に作成/更新され、実際に選ばれた厳密なバージョンとチェックサムを固定します。ロックが存在する限り、通常の init はロックの内容を優先し、勝手なアップグレードは行いません（アップデートは -upgrade を明示）。

チームでの再現性を担保するには、ルートモジュールの .terraform.lock.hcl を VCS にコミットします。再利用目的の公開モジュールではロックファイルを含めないのが一般的です。

• 制約 = 許容範囲、ロック = 実際に使うバージョンとハッシュ
• init はロックを優先。更新は terraform init -upgrade
• ロックはルートモジュールでコミット（再利用モジュールでは通常コミットしない）

最小構成例（制約とロックの関係）

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"  # 5.x のみ許可（制約）
    }
  }
}

# 初回: terraform init で最新の 5.x が選定され、.terraform.lock.hcl に固定
# 以後: terraform init はロックを優先。更新したい時だけ terraform init -upgrade

バージョン制約の書き方と落とし穴

制約は SemVer に基づき、演算子で範囲を定義します。~> は悲観的制約で、指定桁より上位の変更を拒否します。メジャーの上げ止まりを効かせ、パッチ/マイナーの取り込みを許可するのに有効です。

制約を厳しくしすぎるとアップグレードが困難になり、緩すぎると予期せぬ破壊的変更を招きます。チームでは基本方針（例: メジャーロック、マイナー可）を決めて統一しましょう。

• ~> 1.2 は >=1.2.0 かつ <2.0.0
• ~> 1.2.3 は >=1.2.3 かつ <1.3.0
• >=, <=, >, <, =, != をコンマで組み合わせ可能（AND 連結）
• 制約なしは許容範囲が無制限。ロックが無い初回は最新版が選ばれる

代表的な制約パターン

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"        # 5.x の最新を許可
    }
    azurerm = {
      source  = "hashicorp/azurerm"
      version = ">= 3.80, < 4.0" # 明示的な範囲指定
    }
    google = {
      source = "hashicorp/google"
      # version を省略: 制約なし（ロック無ければ最新版が選定）
    }
    github = {
      source  = "integrations/github"
      version = "= 6.3.0"       # 完全固定（推奨は範囲）
    }
  }
}

# 注意: 制約を変更して、ロックに記録されたバージョンが範囲外になると、
# 次回 init でエラーになり、-upgrade の実行が求められます。

依存ロックファイル (.terraform.lock.hcl) の仕組み

.terraform.lock.hcl は、選ばれた各プロバイダの厳密なバージョンと、各プラットフォームごとのチェックサムを保持します。これにより再現性の高い init が可能になります。

通常の terraform init はロックに記録された版を優先し、制約範囲内でも勝手に更新しません。更新したい場合にだけ terraform init -upgrade を用います。複数 OS/アーキで動かす場合は terraform providers lock -platform を使って、対象プラットフォームのチェックサムを事前に追加しておくとよいでしょう。

• 記録内容: provider の source、選定バージョン、プラットフォーム別の SHA256 チェックサム
• ロック更新の契機: terraform init -upgrade、または terraform providers lock
• ロックはルートごとに生成し、リポジトリにコミットして共有

init 時の意思決定フロー（制約・ロック・レジストリ）

ロックの更新と複数プラットフォームのチェックサム追加

# 制約内で最新に更新してロックを書き換える
terraform init -upgrade

# CI/複数OS向けに事前にチェックサムを追加
terraform providers lock \
  -platform=linux_amd64 \
  -platform=darwin_arm64 \
  -platform=windows_amd64

# 変更後は .terraform.lock.hcl をコミット

チーム/CIでの再現性と計画的アップグレード

日常の CI では通常の terraform init を使い、ロックに従って計画/適用を行います。定期的なメンテナンスジョブでのみ -upgrade を使い PR を作ることで、安全に更新を取り込めます。

社内ネットワーク/エアギャップ環境では、CLI 設定ファイルの provider_installation でミラーを優先し、必要に応じて特定プロバイダの直接ダウンロードを禁止して再現性を高めます。

• 日常: init（-upgrade なし）→ validate/plan/apply
• 定期: init -upgrade → .terraform.lock.hcl だけの PR を作成 → 動作確認後にマージ
• ミラー利用時は provider_installation の順序と include/exclude を正しく設定

CI 例（通常パイプラインと週次アップグレード）

# 通常パイプライン
terraform init -input=false
terraform validate
terraform plan -input=false

# 週次のアップグレードジョブ（別ブランチで実行）
terraform init -upgrade -input=false
# ここで .terraform.lock.hcl のみ変更されることを確認し、PR 作成

git add .terraform.lock.hcl
git commit -m "chore: upgrade providers within constraints"
# push → CI で plan を確認

# ミラー設定（~/.terraformrc または terraform.rc）
provider_installation {
  filesystem_mirror {
    path = "/opt/terraform/providers"  # 事前にミラー同期
  }
  direct {
    exclude = ["hashicorp/aws"]         # aws はミラー必須。見つからなければ失敗
  }
}

ありがちなエラーと対処

制約とロックの不一致や、プラットフォーム追加時のチェックサム不足で init が失敗することがあります。エラーメッセージを読み、制約調整または -upgrade、providers lock のいずれが必要かを切り分けます。

ネットワークやミラー設定の不整合でも取得に失敗します。source アドレスの誤りやミラーに該当版が無い、といった基本的な点も見直してください。

• locked version X does not match…: 制約がロックの版を許可していない。制約を緩めるか、init -upgrade
• checksum list for platform is empty: 新しい OS/CPU。providers lock -platform で追記してコミット
• Failed to query available provider packages: source アドレス/ネットワーク/ミラー設定を確認
• どうしても解けない不整合: 最終手段としてロックファイルを再生成（init -upgrade）し差分をレビュー

状況別のコマンド例

# 制約を保ったままロックを更新
terraform init -upgrade

# 新規プラットフォームをロックへ追加
terraform providers lock -platform=linux_arm64

# 制約の見直し例（メジャーを上げる）
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"  # 5.x → 6.x へ移行する場合
    }
  }
}
# その後に init -upgrade を実行

Associate 試験対策の要点チェック

試験では、制約とロックの役割分担、~> の意味、init と -upgrade の使い分け、ロックファイルのコミット方針が頻出です。言い換え問題にも対応できるよう、キーワードで覚えておくと取りこぼしが減ります。

• required_providers は範囲、.terraform.lock.hcl は厳密版を固定
• 通常の terraform init はロック優先、更新は terraform init -upgrade
• ~>1.2 は <2.0、~>1.2.3 は <1.3
• ロックはルートモジュールでコミット。再利用モジュールには通常含めない
• providers lock -platform で複数 OS/CPU のチェックサムを前もって記録

最小の暗記スニペット

terraform {
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 5.0" }
  }
}
# init: ロック尊重 / init -upgrade: 制約内で更新
# ロックはコミットして再現性を担保

問題で確認

よくある質問