Skip to main content

Version Management

ใช้ tfenv หรือ asdf จัดการหลาย Terraform version — สำคัญใน team ที่มี project หลาย version

ทำไมต้องจัดการ Version?​

  • Project A ใช้ Terraform 1.5
  • Project B ใช้ Terraform 1.9
  • ติดตั้งแค่ version เดียว → switch ลำบาก

→ Version manager = solution

Tools​

ToolDescriptionBest For
tfenvTerraform-specificTerraform only
asdfMulti-languageMultiple tools (TF + Node + Python)
mise (rtx)Modern asdf alternativeFaster, similar features

tfenv​

tfenv — most popular for Terraform

Install​

# macOS
brew install tfenv

# Linux
git clone https://github.com/tfutils/tfenv.git ~/.tfenv
echo 'export PATH="$HOME/.tfenv/bin:$PATH"' >> ~/.bashrc

Usage​

# List available versions
tfenv list-remote

# Install
tfenv install 1.9.8
tfenv install 1.5.7
tfenv install latest

# Use
tfenv use 1.9.8
tfenv use latest

# Show current
tfenv version-name

# Uninstall
tfenv uninstall 1.4.0

Per-Project Version (.terraform-version)​

.terraform-version
1.9.8

ใส่ใน root ของ project — tfenv auto switch เมื่อเข้า folder

$ cd project-a
$ terraform version
Terraform v1.5.7    # ← .terraform-version = 1.5.7

$ cd ../project-b
$ terraform version
Terraform v1.9.8    # ← .terraform-version = 1.9.8

Min/Latest Required​

.terraform-version
min-required    # ใช้ version ขั้นต่ำที่ระบุใน required_version

Terraform code:

terraform {
  required_version = ">= 1.5.0"
}

→ tfenv install 1.5.0

asdf​

asdf — multi-language version manager

Install​

brew install asdf

echo '. $(brew --prefix asdf)/libexec/asdf.sh' >> ~/.zshrc

Add Terraform Plugin​

asdf plugin add terraform

Usage​

# List versions
asdf list all terraform

# Install
asdf install terraform 1.9.8
asdf install terraform 1.5.7

# Set global
asdf global terraform 1.9.8

# Set local (per-project)
asdf local terraform 1.9.8

→ Creates .tool-versions:

.tool-versions
terraform 1.9.8
nodejs 20.10.0
python 3.12.1

Auto Switch​

asdf switches auto เมื่อเข้า folder ที่มี .tool-versions

mise (rtx)​

mise — fast modern version manager

# Install
brew install mise

# Add to shell
echo 'eval "$(mise activate zsh)"' >> ~/.zshrc

# Use
mise use [email protected]
.mise.toml
[tools]
terraform = "1.9.8"
nodejs = "20"

Version Constraints in Terraform​

ใช้คู่กับ version manager:

versions.tf
terraform {
  required_version = ">= 1.5.0, < 2.0.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.70"
    }
  }
}

ถ้า CLI version ผิด → fail ทันที:

Error: Unsupported Terraform Core version
This configuration does not support Terraform version 1.4.0

CI/CD with Specific Version​

.github/workflows/terraform.yml
- name: Setup Terraform
  uses: hashicorp/setup-terraform@v3
  with:
    terraform_version: 1.9.8   # specific version

หรือใช้ .terraform-version:

- name: Setup Terraform
  uses: hashicorp/setup-terraform@v3
  with:
    terraform_version: ${{ steps.tfver.outputs.version }}

- name: Read .terraform-version
  id: tfver
  run: echo "version=$(cat .terraform-version)" >> $GITHUB_OUTPUT

Upgrade Strategy​

Patch Upgrades (e.g., 1.9.5 → 1.9.8)​

  • Safe — bug fixes only
  • Test ใน CI ก่อน

Minor Upgrades (e.g., 1.5 → 1.9)​

  • New features, mostly backwards compatible
  • Read release notes
  • Test ใน dev environment

Major Upgrades (e.g., 0.x → 1.x)​

Multi-Version in Team​

.terraform-version (Project A)
1.5.7
.terraform-version (Project B)
1.9.8

ทุกคนติดตั้ง tfenv → auto switch — ทำงานร่วมกันได้

OpenTofu (Alternative to Terraform)​

OpenTofu = community fork ของ Terraform (after BSL license change)

# Install OpenTofu
brew install opentofu

# Use tofu instead of terraform
tofu init
tofu plan
tofu apply

ใช้ syntax + provider เดียวกับ Terraform — drop-in replacement

tenv (alternative tfenv ใหม่)​

tenv = modern version manager รองรับ:

  • Terraform
  • OpenTofu
  • Terragrunt
  • Atmos
brew install cosmtrek/tap/tenv

tenv tf install 1.9.8
tenv tofu install 1.7.0
tenv tg install 0.62.0

# Auto switch
tenv update-path

ตัวอย่าง: Project Setup​

my-project/
├── .terraform-version    # 1.9.8
├── .tflint.hcl
├── .pre-commit-config.yaml
├── main.tf
├── variables.tf
├── outputs.tf
└── versions.tf
versions.tf
terraform {
  required_version = "~> 1.9.0"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.70"
    }
  }
}
.terraform-version
1.9.8
.pre-commit-config.yaml
repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.96.0
    hooks:
      - id: terraform_fmt
      - id: terraform_validate

Best Practices​

✅ DO:
- ใช้ tfenv / asdf / mise
- Pin version ใน .terraform-version
- Match version ระหว่าง local + CI
- Upgrade ใน dev ก่อน prod
- Read changelog ก่อน upgrade

❌ DON'T:
- ห้ามมีหลาย Terraform version ใน CI โดยไม่ตั้งใจ
- ห้าม pin patch ที่ stale มาก
- ห้าม skip changelog ตอน upgrade major

ตัวอย่าง: Upgrade Workflow​

Step 1: Update .terraform-version​

echo "1.10.0" > .terraform-version
tfenv install 1.10.0

Step 2: Read Changelog​

ดู GitHub releases

Step 3: Plan + Test​

terraform init -upgrade
terraform plan
# ดู diff — ควรเป็น 0 changes

Step 4: Update CI​

- uses: hashicorp/setup-terraform@v3
  with:
    terraform_version: 1.10.0

Step 5: Apply Dev​

terraform apply

Step 6: Apply Prod (after monitoring dev)​

สรุป​

  • tfenv / asdf / mise = version managers
  • .terraform-version = per-project version
  • Match local + CI versions
  • Upgrade carefully — patch first, then minor, then major
  • OpenTofu = open-source fork (drop-in replacement)
  • tenv = modern tool รองรับหลาย binary

ต่อไป → Terragrunt