Provider and Terraform Versions
Providers release new versions often. If Crumb's pipeline quietly picks up a new major version with breaking changes, a routine plan can suddenly want to change things nobody touched. Version constraints prevent that surprise.
The rule
Constrain the range in code; the lock file freezes the exact pick.
A version constraint is a string of conditions:
terraform {
required_version = ">= 1.6.0"
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0"
}
}
}required_versionlimits which Terraform CLI versions may run this configuration.versioninsiderequired_providerslimits which provider versions are acceptable.
Operators: =, !=, >, >=, <, <=, and the pessimistic operator ~>, which allows only the rightmost number given to grow:
| Constraint | Allows |
|---|---|
~> 5.0 |
5.0 and up, below 6.0 |
~> 5.31 |
5.31 and up, below 6.0 |
~> 5.31.0 |
5.31.0 and up, below 5.32.0 |
>= 5.0, < 5.50 |
a range written out in full |
The constraint is a range. The dependency lock file, .terraform.lock.hcl, records the exact provider version that terraform init chose, plus checksums. Commit it. From then on everyone gets that same version, even if a newer one in the range exists. To move forward on purpose, run terraform init -upgrade, which picks the newest version the constraints allow and rewrites the lock file.
The lock file covers providers only. It does not pin the Terraform CLI, which required_version handles, nor module versions, which have their own version argument on each module call.
The shortcut
For ~>, cover the last number with your thumb; everything to its left is frozen. ~> 5.31 freezes the 5; ~> 5.31.0 freezes 5.31.
Read the constraint
~> 5.0has two numbers. Cover the last one:5stays frozen.
The trap: leaving the lock file out of Git. Each machine then chooses its own version inside the range, and plans differ between laptops.
Drills
Answer fast — trust the rule.
Which versions does ~> 5.0 allow?
Which versions does ~> 5.31.0 allow?
What does .terraform.lock.hcl record?
A newer 5.x provider is released. Your constraint is ~> 5.0 and the lock file says 5.61.0. What does a plain terraform init install?
Which setting limits the Terraform CLI version itself?
Remember
- Constraints set the allowed range; the lock file freezes the exact version. Commit it.
- Shortcut for
~>: cover the last number; the rest is frozen. - Trap: no lock file in Git means different versions on different machines.