Terraform Module Sources and Versioning
A module is a package of code, and every package has an address and an edition. The address tells Terraform where to fetch the module. The edition tells Terraform which release to use. Skip the edition and one morning your plan shows surprise changes because the author published a new release overnight. Pinned versions keep your infrastructure steady and your results repeatable.
The Source Argument
Every module call needs a source. Terraform reads that value during terraform init and downloads the module into the .terraform/modules folder.
Diagram: Where Modules Come From
+----------------------+
| Your Root Module |
| module "network" {} |
+----------+-----------+
|
+------------------+-------------------+
| | |
v v v
+---------------+ +----------------+ +----------------+
| Local folder | | Terraform | | Git repository |
| ./modules/net | | Registry | | GitHub, GitLab |
+---------------+ +----------------+ +----------------+Local Path Sources
A local path points to a folder on the same machine. Local modules suit code that lives inside one project.
module "network" {
source = "./modules/network"
}Local paths must start with ./ or ../. Terraform has no version concept for local folders because the files are right there.
Registry Sources
The Terraform Registry hosts public modules. The address follows the pattern namespace/name/provider.
module "vpc" {
source = "terraform-aws-modules/vpc/aws"
version = "~> 5.0"
}Git Sources
A Git source pulls a module straight from a repository. Teams use this for private modules.
module "network" {
source = "git::https://github.com/example-org/terraform-network.git?ref=v1.2.0"
}The ref value selects a tag, a branch, or a commit. A tag such as v1.2.0 gives the safest result because tags do not move. A branch name moves every time someone pushes, which breaks repeatability.
Git Source Variations
| Goal | Source Format |
|---|---|
| Specific tag | git::https://github.com/org/repo.git?ref=v1.2.0 |
| Folder inside a repository | git::https://github.com/org/repo.git//modules/network?ref=v1.2.0 |
| SSH access | git::ssh://git@github.com/org/repo.git?ref=v1.2.0 |
Version Constraints
The version argument works only with registry modules. It accepts a constraint, which describes a range of acceptable releases.
| Constraint | Meaning | Accepts |
|---|---|---|
"5.1.0" | Exactly this release | 5.1.0 |
">= 5.0" | This release or newer | 5.0, 5.4, 6.0, 7.2 |
"~> 5.1" | Newer within the same major version | 5.1, 5.2, 5.9. Rejects 6.0 |
"~> 5.1.0" | Newer patches only | 5.1.1, 5.1.9. Rejects 5.2.0 |
">= 5.0, < 6.0" | A custom range | 5.0 up to 5.x |
Understanding Version Numbers
5 . 2 . 1
| | |
| | +-- Patch: small bug fixes
| +------ Minor: new features, same behavior
+---------- Major: changes that can break your codeThe pessimistic operator ~> lets Terraform accept safe updates and blocks the risky major jump. It is the most popular choice for shared modules.
Updating Modules Safely
Terraform downloads a module once and reuses it. A new release never arrives on its own. Follow these steps to upgrade.
- Change the
versionorrefvalue in the module block. - Run
terraform init -upgradeto fetch the new release. - Run
terraform planand read every proposed change. - Apply only when the plan matches your expectations.
Provider Lock File Versus Module Versions
The .terraform.lock.hcl file records provider versions only. It does not record module versions. Pin modules inside the module block itself, and commit the lock file to Git so teammates share the same provider builds.
Good Habits for Module Sources
- Pin every registry module with a version constraint.
- Pin every Git module with a tag.
- Read the changelog before a major upgrade.
- Test upgrades in a development environment first.
- Use semantic version tags such as
v1.4.2for your own modules.
Key Points
- The
sourceargument tells Terraform where to fetch a module. - Sources include local paths, the public registry, and Git repositories.
- The
versionargument works only with registry modules. - Git modules use
?ref=with a tag for fixed releases. - The
~>operator accepts safe updates and blocks major jumps. - Run
terraform init -upgradeto pull a newer release on purpose.
