Module 5: Terraform Modules

Lesson 5.4: Managing Module Versions

Plain language

Registry modules use the same constraint operators as providers (Module 2):

HCL
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.8"  # ≥ 5.8.0, < 6.0.0
}

For non-registry sources, the ref is the version:

HCL
module "site" {
  source = "git::https://github.com/acme/tf-course-site-module.git?ref=v1.1.0"
}

Under the hood

Action Behavior
terraform init with modules already installed Keeps the installed versions if they still satisfy the constraints
terraform init -upgrade Re-resolves every module (and provider) to the newest version allowed
Change version or ref Run init again. Plan errors until you do, saying the module isn't installed or its source changed.
Lock file Doesn't record modules. Constraints and refs are the only pins.

Best practices

  • Pin production root modules to an exact version or a tight ~> range. Upgrade deliberately, through PRs.
  • Use tags or commit SHAs for Git sources, never a moving branch like main.
  • A new module version can change resource addresses. Well-maintained modules ship moved blocks so that callers aren't forced to recreate resources.
  • In HCP Terraform, a private registry gives internal modules registry-style version support (Module 8).