Terraformモジュールのバージョニング実務: sourceとversionの運用指針

Terraformのモジュールはsourceで取得元を指定し、レジストリ経由の場合のみversionで制約できます。Git等のURLソースではversionは無効で、タグやコミットをrefで固定します。

この記事は、実務で壊れないアップグレードを実現するための最小原則と、資格試験で問われやすいポイントを一気通貫でまとめました。

基本整理: sourceは必須、versionはレジストリ専用

moduleブロックではsourceが必須です。レジストリ経由のモジュールのみversion引数でバージョン制約が使えます。Gitやローカルパスなどレジストリ以外のソースではversionは使えず、初期化時にエラーになります。

GitなどURLベースのソースでは、refクエリでタグ名、ブランチ、またはコミットSHAを指定して固定します。再現性重視ならタグまたはコミットSHAでの固定が基本です。

• レジストリソース: sourceはregistryアドレス、versionで制約可能
• URLソース(Git/HTTP等): versionは不可、refで固定
• ローカルモジュール: バージョン管理は不要。変更はそのまま反映される
• プロバイダのrequired_providersのversionと、モジュールのversionは別物

モジュール解決の流れ

module "x" {
  source  +  version?        terraform init
    |            |                 |
    |            |           依存解決エンジン
    |            |                 v
    +--> ソースアドレス ----> 取得元判定
           |                         |
           |                         +--> レジストリ: version制約を解決し最新版選択
           |                         |
           |                         +--> Git/HTTP等: refがあればそのタグ/コミットを取得
           v                                  (なければデフォルトブランチ)
    .terraform/modules に展開

レジストリ経由の基本例

terraform {
  required_version = ">= 1.3"
}

module "consul" {
  source  = "hashicorp/consul/aws"   # レジストリアドレス
  version = "~> 0.10"                 # 0.10.x に固定（将来の0.11系は除外）
}

ソース種別ごとの固定方法と落とし穴

試験でも実務でも混同しやすいのが、レジストリとGitの指定差分です。versionが使えるのはレジストリのみ。Gitではref=でタグやコミットを指定します。ローカルパスやHTTPアーカイブもversionは使えません。

再現性の確保が最優先です。本番ではブランチ固定(mainやmaster)ではなく、タグやコミットSHAで固定しましょう。

• レジストリ: versionでセマンティックバージョンの範囲指定が可能
• Git: ref=タグ名やref=コミットSHAで固定。範囲指定は不可
• HTTP/S3/GCSアーカイブ: URLにハッシュ付きの不変オブジェクトを推奨
• ローカル: チーム共有には不向き。再現性はVCS管理前提

Gitタグでの固定例とサブディレクトリ指定

module "vpc" {
  source = "git::https://github.com/org/terraform-modules.git//network/vpc?ref=v1.2.3"
}

module "eks" {
  source = "git::ssh://[email protected]/org/iac.git//modules/eks?ref=9f2c0abd1"
}

Terraform Cloud/Enterpriseの私有レジストリ運用

Terraform Cloud/Enterpriseのプライベートモジュールレジストリでは、sourceに app.terraform.io/<org>/<name>/<provider> を使い、versionで制約します。VCS上のリリースタグ(SemVer)を登録し、利用側はversion制約で受け取ります。

初回はterraform loginで認証を行い、init時にモジュールが解決されます。アップグレードはコード上のversion制約を保ちつつ、terraform init -upgradeで許容範囲の最新に更新します。

• SemVerタグ(例: v2.4.1)をVCSで作成し、レジストリに公開
• 利用側はversion = "~> 2.4" 等の範囲指定でパッチ更新を許可
• ブレイキング変更はメジャーアップ、後方互換はマイナー/パッチで
• 認証はCLI configまたはterraform loginで設定

私有レジストリ利用例

module "network" {
  source  = "app.terraform.io/acme/network/aws"
  version = "~> 2.4"   # 2.4.x を許容
}
# 初回認証: terraform login

制約式の設計パターン: 安定性と更新容易性の両立

レジストリ経由ではSemVer準拠の制約を使います。~> 演算子は「左から2成分を固定する」慣用で、~> 1.2 は >= 1.2.0 かつ < 1.3.0 を意味します。プロダクションはパッチだけ許容、ステージングはマイナーまで許容など、環境別に設計できます。

Gitソースには範囲指定はなく、タグやコミットで明示的に更新します。自動更新を期待するならレジストリへの登録とversion制約を選びます。

• パッチのみ自動: version = "~> 2.4"
• マイナーまで自動: version = "~> 2"
• 完全固定: version = "= 2.4.3" または Gitのref=タグ/コミット
• プレリリースはSemVer準拠の比較。原則、本番では避ける

制約式の具体例

module "web" {
  source  = "app.terraform.io/acme/web/aws"
  version = "~> 1.8"     # 1.8.x
}

module "batch" {
  source  = "app.terraform.io/acme/batch/aws"
  version = ">= 2.3, < 3.0"  # 複合条件
}

# Gitは範囲不可。タグ/コミットで固定
module "ops" {
  source = "git::https://github.com/acme/ops-mods.git//alerts?ref=v0.9.5"
}

アップグレード手順とCIへの組み込み

レジストリ経由のモジュールは、既にダウンロード済みであればinitは同じ版を再利用します。許容範囲内で新しい版に上げるには terraform init -upgrade を実行します。Gitソースはコード中のrefを書き換えない限り更新されません。

依存のロックファイル(.terraform.lock.hcl)はプロバイダ専用で、モジュールには適用されません。再現性はversion制約(Gitならタグ/コミット固定)と、.terraformディレクトリの再作成で担保します。

• レジストリ: 変更なしのinitは再解決しない。-upgradeで再解決
• Git: refを更新しない限り不変。CIで勝手に最新化されない
• .terraform/ はキャッシュ。再現時は削除してinitし直す
• planの前にinit -upgradeをジョブに明示

CIジョブ例

# Bash例
set -euo pipefail
rm -rf .terraform/          # クリーンに再現
terraform init -upgrade
terraform validate
terraform plan -out=tfplan

アンチパターンと試験の落とし穴

Gitソースでversionを指定してしまう、という誤りは試験でも頻出です。versionはレジストリ専用で、Gitはrefです。また、mainなどのブランチ固定は常に変動するため本番では避けます。

providerのversionピン留めとmoduleのversionピン留めを混同しないこと。required_providersはプロバイダのみ、moduleのversionはレジストリモジュールのみです。

• 誤り: Gitソースにversionを付ける → エラー
• 誤り: 本番でブランチ固定(ref=main) → 予期せぬ差分
• 誤り: moduleの更新をinitだけで期待 → -upgradeが必要
• 正解: レジストリはversion、Gitはref、ローカルはそもそも固定不要

悪い例と良い例

# 悪い例: Gitにversionを書いている
module "bad" {
  source  = "git::https://github.com/org/mods.git//vpc"
  version = "~> 1.2"   # ← エラー: versionは無効
}

# 良い例: Gitタグで固定
module "good_git" {
  source = "git::https://github.com/org/mods.git//vpc?ref=v1.2.3"
}

# 良い例: レジストリで範囲指定
module "good_registry" {
  source  = "app.terraform.io/acme/vpc/aws"
  version = "~> 1.2"
}

問題で確認

よくある質問