Module Versioning Best Practices
What you'll learn: How to apply semantic versioning and maintain clear changelogs so your Terraform modules remain stable and predictable across releases.
Why Version Your Modules
When you publish or share Terraform modules (either internally or via the Terraform Registry), users depend on them not breaking unexpectedly. Without proper versioning, a module update could silently introduce breaking changes that destroy infrastructure or cause plan failures. Versioning creates a contract between module authors and consumers.
Semantic Versioning (SemVer)
Use the MAJOR.MINOR.PATCH format (e.g., v1.3.2):
- MAJOR (1.x.x): Breaking changes—renaming required variables, removing outputs, changing resource addresses
- MINOR (x.3.x): New features added in a backward-compatible way—new optional variables, additional outputs
- PATCH (x.x.2): Backward-compatible bug fixes—typo corrections, documentation updates
Example: If your module is at v2.1.4 and you add a new optional variable, release v2.2.0. If you rename a required input variable, jump to v3.0.0.
Changelog Practices
Maintain a CHANGELOG.md file that documents every version:
## [2.1.0] - 2024-01-15
### Added
- New optional variable `enable_monitoring`
## [2.0.0] - 2024-01-01
### Changed
- BREAKING: Renamed `instance_type` to `vm_size`
This helps users understand what changed before upgrading.
Tagging and Pinning
Tag your module repository with version tags (git tag v1.2.3). Users should pin to specific versions in their module blocks to prevent surprises:
module "example" {
source = "git::https://github.com/org/module.git?ref=v1.2.3"
}
Key Takeaway: Use semantic versioning to signal breaking changes (major), features (minor), and fixes (patch), and maintain a changelog so module consumers can upgrade confidently without unexpected infrastructure changes.