Course contentsShow
← Cloud and Infrastructure
Lesson 811 of 2,98915. Terraform in PracticeFree lesson

Module Versioning Best Practices

Applying semantic versioning and changelog practices to maintain stable module releases.

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.