Plain language
Registry modules use the same constraint operators as providers (Module 2):
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:
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
movedblocks so that callers aren't forced to recreate resources. - In HCP Terraform, a private registry gives internal modules registry-style
versionsupport (Module 8).