In the previous subchapter, we insisted on "always pinning the version" of a module. Now we'll see why this is so important and how to do it when the module is yours and lives in a Git repository. Module versioning is what allows you to use them safely and predictably as a team, without an unexpected change breaking your infrastructure.

Imagine your company has a corporate-network module in a Git repository, used by ten projects. One day, someone improves the module and changes how it creates subnets. If all ten projects automatically used "the latest version" of the module, all would be affected by that change at once, without warning. The next terraform plan for each project would show unexpected—and possibly dangerous—changes.

You need a way to say "I use this specific version of the module, and it won't change until I decide to update." That's what versions are for.

A Git tag is a named marker you put on a specific point in a repository's history. It's used to mark versions. The most widespread convention is semantic versioning: numbers like v1.4.2.

Each tag is a stable "snapshot" of the module at a given moment. Once created, it does not change: v1.0.0 will always be exactly that code.

The format vMAJOR.MINOR.PATCH (e.g., v2.3.1) communicates the type of change:

So, at a glance, you know the risk of updating: going from v1.2.0 to v1.3.0 (minor change) is safe; moving to v2.0.0 (major change) may require adjustments.

When referencing a module from a Git repository, you specify which version (tag) you want to use with ref:

And for Registry modules (subchapter 18.3), with the version argument:

In both cases, you tell Terraform: "use exactly this version." Even if the module evolves, your project will keep using the version you pinned, stable and predictable, until you decide to change the number.

With versioning, each project controls when to update:

Advantages:

• Stability: your infrastructure doesn't change unless you decide.
• Controlled updates: you upgrade when you're ready, reviewing the plan (subchapter 12.5) and testing first.
• Reproducibility: anyone running your code gets the same result, because the module version is pinned.
• Safe teamwork: different projects use different versions without interfering with each other.

Real-world example: the platform team publishes corporate-network v2.0.0 with an important improvement that requires adjustments (major change). Instead of imposing it on everyone at once, each project team migrates to v2.0.0 when they can: they read the release notes, test in their development environment, review the plan, and then update production. No one is caught off guard. Versioning turns a potentially chaotic update into an orderly process.

This fits perfectly with what we saw in subchapter 12.5 (PR review of plans). Updating a module version is a code change that goes through a Pull Request: you change ref=v1.2.0 to ref=v2.0.0, CI shows the plan with what that implies, a teammate reviews it, and only then is it applied. Versioning + plan review = safe and traceable infrastructure changes.

• Without versioning, a change in a shared module would instantly affect all projects using it, without control: dangerous.
• A Git tag marks a stable and immutable version of the module. The convention is semantic versioning: vMAJOR.MINOR.PATCH.
• The numbers communicate the risk: MAJOR = incompatible changes (be careful), MINOR = new compatible functionality, PATCH = safe fixes.
• Pin the version with ref=vX.Y.Z (Git modules) or version = "X.Y.Z" (Registry): your project uses exactly that version until you decide to change it.
• Benefits: stability, controlled updates, reproducibility, and safe teamwork. Fits with the PR review of plans workflow (subchapter 12.5).

In the last subchapter of the chapter, we'll look at an important design dilemma: when to create generic modules (highly reusable) versus domain-specific modules.