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

GoalSource Format
Specific taggit::https://github.com/org/repo.git?ref=v1.2.0
Folder inside a repositorygit::https://github.com/org/repo.git//modules/network?ref=v1.2.0
SSH accessgit::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.

ConstraintMeaningAccepts
"5.1.0"Exactly this release5.1.0
">= 5.0"This release or newer5.0, 5.4, 6.0, 7.2
"~> 5.1"Newer within the same major version5.1, 5.2, 5.9. Rejects 6.0
"~> 5.1.0"Newer patches only5.1.1, 5.1.9. Rejects 5.2.0
">= 5.0, < 6.0"A custom range5.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 code

The 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.

  1. Change the version or ref value in the module block.
  2. Run terraform init -upgrade to fetch the new release.
  3. Run terraform plan and read every proposed change.
  4. 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.2 for your own modules.

Key Points

  • The source argument tells Terraform where to fetch a module.
  • Sources include local paths, the public registry, and Git repositories.
  • The version argument 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 -upgrade to pull a newer release on purpose.