Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 37 ยท Modules

Module Sources, the Registry and Version Constraints

Use modules from the Terraform Registry, Git and local paths, pin them with version constraints (~>, >=), upgrade safely and publish your own modules.

You do not have to write every module yourself. The public Terraform Registry hosts thousands of modules, and the same module block can pull code from a local folder, a Git repository, an S3 bucket or a private registry. Choosing where code comes from, and how tightly you pin its version, decides whether your next terraform init is boring (good) or breaks production (bad).

Where modules can come from

The source argument accepts several forms:

HCL
# Local path: always the code in your repository
module "network" { source = "./modules/network" }

# Public registry: NAMESPACE/NAME/PROVIDER
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.8"
}

# Git over HTTPS, pinned to a tag
module "queue" { source = "git::https://github.com/acme/tf-queue.git?ref=v1.4.2" }

# Git over SSH, a subdirectory, a branch
module "dns" { source = "git::ssh://[email protected]/acme/infra.git//modules/dns?ref=main" }

# Generic HTTP archive or S3 bucket
module "zip" { source = "https://example.com/modules/network-1.2.0.zip" }
module "s3"  { source = "s3::https://s3-eu-west-1.amazonaws.com/acme-modules/net.zip" }

# Private registry (HCP Terraform or your own)
module "svc" {
  source  = "app.terraform.io/acme/service/aws"
  version = "2.1.0"
}

Notes:

  • The double slash // separates the repository from a subdirectory inside it.
  • Only registry sources support the version argument. For Git, pin with ?ref= to a tag or commit SHA. A branch name moves under you.
  • terraform init downloads modules into .terraform/modules. Run terraform init -upgrade to fetch newer versions that still satisfy the constraints.

Version constraint syntax

Constraints are comma-separated conditions that must all hold:

Expression Meaning
"1.2.0" or "= 1.2.0" Exactly this version
">= 1.2" This or newer (risky: allows major jumps)
"< 2.0" Older than 2.0
">= 1.2, < 2.0" A range
"~> 1.2" >= 1.2, < 2.0 (only the rightmost part may rise)
"~> 1.2.3" >= 1.2.3, < 1.3.0

The ~> ("pessimistic") operator is the one you will use most: it accepts bug-fix and minor releases but not a new major version. The same syntax applies to required_version for Terraform itself and to required_providers versions.

HCL
terraform {
  required_version = "~> 1.9"
  required_providers {
    aws = { source = "hashicorp/aws", version = "~> 5.60" }
  }
}

A constraint resolver

Resolving a constraint means picking the newest available version that satisfies all conditions. The program below implements the operators above on a list of released versions, which is exactly what init does for you.

Python Which version does Terraform pick?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The lock file protects providers, not modules

terraform init writes .terraform.lock.hcl, which records the exact provider versions and checksums used. Commit it: it makes every machine and CI run use the same provider build. Modules are not locked. For them, an exact version = "5.8.1" or a Git commit SHA is the only guarantee of repeatability. Many teams use ~> for well-known public modules and exact pins plus automated update pull requests (Renovate, Dependabot) for everything else.

flowchart LR
  C["Constraint in .tf: ~> 5.8"] --> I["terraform init"]
  I --> L[".terraform.lock.hcl (providers)"]
  I --> D[".terraform/modules (downloaded code)"]
  L --> P["plan / apply uses the same provider build"]

Commit the lock file; treat module versions as part of your code review.

Upgrading safely

  1. Read the module's changelog for breaking changes.
  2. Raise the version constraint on a branch, run terraform init -upgrade.
  3. Run terraform plan and read it carefully: a harmless-looking minor upgrade that wants to replace a database is a red flag.
  4. Apply in a non-production environment first.

Publishing your own module

To publish to the public registry, your repository must be on GitHub, named terraform-PROVIDER-NAME (for example terraform-aws-queue), have a root module with main.tf, variables.tf and outputs.tf, and publish releases as semantic-version Git tags such as v1.0.0. Private registries in HCP Terraform work with the same naming and tag rules. Follow semantic versioning: breaking interface changes bump the major number (Module Design).

OpenTofu note

OpenTofu has its own registry (registry.opentofu.org) that mirrors most public modules and providers. Sources written without a hostname resolve against it, and version constraints use the same syntax.

Python Check a lock file entry

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which versions does the constraint ~> 1.2 allow?

    ~> lets only the rightmost specified component rise: 1.2 allows 1.9 but not 2.0.
  2. 2. How do you pin a Git-sourced module?

    The version argument is registry-only; for Git use ?ref=.
  3. 3. What does .terraform.lock.hcl record?

    It locks providers. Pin modules explicitly.
  4. 4. What does the // in a module source separate?

    git::https://host/repo.git//modules/dns selects the modules/dns folder.

Summary

  • Modules can come from local paths, the Registry, Git, HTTP archives, S3 and private registries.
  • Use version for registry sources and ?ref= for Git; prefer tags or commit SHAs over branches.
  • ~> accepts safe upgrades; ranges combine with commas.
  • Commit .terraform.lock.hcl for providers; pin modules deliberately and upgrade through reviewed plans.
  • Publish modules as terraform-PROVIDER-NAME repositories with semantic-version tags.

Next: count and for_each with Modules, and Testing Modules