Terraform Module Versioning

In Terraform, module versioning ensures you use a specific, stable version of a module instead of always pulling the latest code.

👉 This avoids breaking changes and keeps infrastructure predictable.

---

🔹 1. Why Module Versioning?

• Prevent unexpected changes
• Maintain stability across environments
• Enable rollback to previous versions
• Support team collaboration

---

🏷️ 2. Versioning with Git (Most Common)

Modules stored in GitHub can be versioned using:

✅ Git Tags (Recommended)

git tag v1.0.0
git push origin v1.0.0

---

🔗 3. Use Version in Terraform

module "rg" {
  source = "git::https://github.com/org/repo.git//modules/rg?ref=v1.0.0"

  rg_name     = "my-rg"
  rg_location = "eastus"
}

👉 ?ref= supports:

• Tag → v1.0.0 ✅ best
• Branch → main
• Commit → a1b2c3d

---

📦 4. Terraform Registry Versioning

If using Terraform Registry:

module "rg" {
  source  = "app.terraform.io/org/rg-module/azurerm"
  version = "1.0.0"
}

👉 Uses semantic versioning (SemVer)

---

🔢 5. Semantic Versioning (Best Practice)

Format:

MAJOR.MINOR.PATCH

Example:

• 1.0.0 → initial release
• 1.1.0 → new feature (no breaking)
• 2.0.0 → breaking changes

---

🧠 6. Version Constraints

version = "~> 1.0"

👉 Means:

• Allow: 1.0.x, 1.1.x
• Block: 2.0.0

---

⚠️ 7. Without Versioning (Risk)

source = "git::https://github.com/org/repo.git"

❌ Always pulls latest → risky
❌ Can break production

---

🎯 8. Best Practices

• ✅ Always use version/tag
• ✅ Follow semantic versioning
• ✅ Avoid using main in production
• ✅ Maintain changelog
• ✅ Test before upgrading versions

---

🧩 Real-World Flow

1. Develop module
2. Tag version (v1.0.0)
3. Use in projects
4. Update module → release v1.1.0
5. Upgrade safely

---

✅ Summary

• Module versioning = stable infrastructure
• Use ?ref= for Git modules
• Use version for registry modules
• Follow SemVer best practices