バージョン制約式 — ~> / >= / != の使い方

by

1. 概要

バージョン制約式（~> / >= / !=）で、TerraformとプロバイダーのバージョンをHCLで宣言的に管理します。チームのバージョン統一・意図しないメジャーアップグレード防止に必須の知識です。

2. バージョン制約演算子

演算子意味例
= 1.9.0 または 1.9.0完全一致1.9.0のみ
!= 1.9.0除外1.9.0以外
>= 1.9.0以上1.9.0以上すべて
<= 1.9.0以下1.9.0以下すべて
> 1.9.0より大きい1.9.1以上
< 1.9.0より小さい1.8.x以下
~> 1.9悲観的制約（マイナー互換）1.9.x（2.0は除く）
~> 1.9.0悲観的制約（パッチ互換）1.9.0〜1.9.x（1.10は除く）

3. ~>（チルダ・グレータ）演算子

~>は「悲観的制約演算子」と呼ばれ、最も右の数字のみ変動を許します。

# ~> 1.9    → 1.9.0以上 2.0未満（マイナーバージョンまで固定）
# ~> 1.9.0  → 1.9.0以上 1.10.0未満（パッチバージョンのみ変動可）
# ~> 5.0    → 5.0.0以上 6.0.0未満

4. required_version の設定

terraform {
  required_version = ">= 1.9"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }
}

provider "aws" {
  region = "ap-northeast-1"
}

variable "environment" {
  description = "環境名"
  type        = string
  default     = "dev"
}

推奨パターン:

# ✅ 推奨: >= でTerraform 1.9以上を要求
terraform {
  required_version = ">= 1.9"
}

# ✅ 推奨: 範囲指定でメジャーアップグレードを防ぐ
terraform {
  required_version = ">= 1.9, < 2.0"
}

# ❌ 避ける: 完全一致はメンバーのバージョン差異でエラーになる
terraform {
  required_version = "= 1.9.8"
}

バージョン制約に違反するとError: Unsupported Terraform Core versionエラーが発生します。

5. required_providers のバージョン制約

terraform {
  required_version = ">= 1.9"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      # ~> 5.0 → 5.0.x は許可、6.0.0 は禁止
      version = "~> 5.0"
    }
    random = {
      source  = "hashicorp/random"
      version = ">= 3.0, < 4.0"
    }
  }
}

プロバイダーのバージョン固定パターン:

# .terraform.lock.hcl でバージョンをロック（terraform init後に生成）
# このファイルはGitにコミットしてチームで共有する

# プロバイダーのアップグレード
# $ terraform init -upgrade

6. .terraform.lock.hcl との関係

terraform initを実行すると.terraform.lock.hclが生成されます。このファイルはプロバイダーの正確なバージョンとチェックサムを記録します。

# .terraform.lock.hcl（自動生成・変更しない）
provider "registry.terraform.io/hashicorp/aws" {
  version     = "5.60.0"
  constraints = "~> 5.0"
  hashes = [
    "h1:xxxx...",
  ]
}

.terraform.lock.hclはGitにコミットする（.gitignoreに含めない）。

7. バージョン制約のベストプラクティス

terraform {
  # Terraformバージョン: >=でCI/CDのバージョン差を許容
  required_version = ">= 1.9"

  required_providers {
    aws = {
      source = "hashicorp/aws"
      # プロバイダー: ~>でメジャーバージョンを固定
      version = "~> 5.0"
    }
  }
}

メンバー全員が同じプロバイダーバージョンを使うには、.terraform.lock.hclをGitにコミットしてterraform initでインストールするのが確実です。

8. 関連記事

9. まとめ

  • ~> 1.9 — 1.9.x系のみ許可（最も右の数字のみ変動を許す）
  • >= 1.9 — 1.9以上すべて許可（チームでは最も使いやすいが上限なし）
  • >= 1.9, < 2.0 — 上限付き範囲指定（メジャーアップグレードを防ぐ）
  • required_versionはTerraform本体のバージョン、required_providersはプロバイダーのバージョン
  • .terraform.lock.hclをGitにコミットしてプロバイダーバージョンをチームで固定する

動作確認バージョン: Terraform >= 1.9 公式ドキュメント: https://developer.hashicorp.com/terraform/language/expressions/version-constraints