Skip to main content

Module Versioning

Module Versioning
Snapshotting Infrastructure Blueprints

Imagine you’re building your Lego city with Terraform modules. One day, the Lego company releases a new version of the hospital set with better design, more pieces. But if you swap it in without checking, your city might break!

Terraform modules are the same: they evolve, and versioning lets you control when and how you adopt changes. This chapter teaches you how to pin, upgrade, and manage module versions safely.

Key Concepts

1. Why Versioning Matters

  • Modules evolve with bug fixes, new features, or breaking changes.
  • Without versioning, updates may break your infrastructure.
  • Versioning ensures stability and predictability.

2. Pinning Versions

  • Prevents accidental upgrades when the module changes upstream.

Always specify a version when using registry modules:

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.0.0"
}

3. Semantic Versioning (SemVer)

  • Modules follow MAJOR.MINOR.PATCH format:
    • MAJOR: Breaking changes.
    • MINOR: New features, backward compatible.
    • PATCH: Bug fixes, backward compatible.
  • Example: 5.0.0 → 5.1.0 (safe minor upgrade).

4. Version Constraints

  • Use operators to control upgrades:
    • >= 5.0.0 → Any version 5.0.0 or higher.
    • ~> 5.0 → Any 5.x version, but not 6.x.
    • = 5.0.0 → Exact version only.

Hands‑On Lab / Demo

Lab: Pinning and Upgrading a Module

  1. Run terraform init → downloads version 5.0.0.
  2. Upgrade to 5.1.0:
    • Change version in config.
    • Run terraform init -upgrade.
    • Run terraform plan → check for changes before applying.

Use a VPC module pinned to version 5.0.0:

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "5.0.0"
  cidr    = "10.0.0.0/16"
}

Pro Tips & Best Practices

  • Always pin versions for registry modules.
  • Use ~> constraints for safe minor upgrades.
  • Test upgrades in staging before production.
  • Document module versions in README for clarity.
  • Avoid floating versions (latest) - they’re unpredictable.

Summary & Cheatsheet

  • Versioning = Stability.
  • Pin versions: Prevent accidental upgrades.
  • SemVer: MAJOR (breaking), MINOR (features), PATCH (fixes).
  • Constraints: =, >=, ~> for control.
Quick mnemonic: Pin, Plan, Upgrade

The Hackers Notebook

Module versioning is the safety net of Terraform modules. It ensures your infrastructure remains stable while still allowing you to adopt improvements at your own pace. By mastering versioning, you gain control over change management in Terraform.

Tips, Tricks, Roadmaps, Resources, Networking, Motivation, Guidance, and Cool Stuff ♥
Updated on Dec 31, 2025