Versioning and Version Constraints

Version constraints control which versions of providers and modules Terraform will use — ~> 6.0, >= 1.2, < 2.0. They are the difference between a reproducible build and one that drifts every time upstream ships a release. The pessimistic operator ~> and the dependency lock file together give you the goal: new patches automatically, breaking changes never by surprise.

Unconstrained dependencies are a slow-motion outage. A config with no version pins works today, then a teammate runs a fresh init next month, pulls a new major version, and inherits breaking changes nobody chose. Constraints turn that random event into a deliberate, reviewed upgrade.

Constraint Syntax

A constraint is one or more comparison rules. = 6.1.0 pins an exact version. >=, <=, >, and < set bounds, and you combine them with commas: >= 6.1.0, < 7.0.0 accepts anything in that range. The most common operator is ~>, the pessimistic constraint, which encodes "this minor line, no further." Each rule narrows the set of acceptable versions; Terraform picks the newest version that satisfies all of them.

The Pessimistic Operator

The ~> operator allows the rightmost component to increase and nothing above it. ~> 6.0 allows any 6.x — 6.1, 6.7, 6.42 — but not 7.0. ~> 6.1.0 is tighter: it allows 6.1.x only, so 6.1.3 is in but 6.2.0 is out. That one extra digit is the difference between "accept all minor and patch updates in the 6 line" and "accept patch updates to 6.1 only," and misreading it is a common way to get more or less than you intended.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"    # any 6.x, never 7.0
    }
  }
}

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 6.1.0"          # 6.1.x only
  name    = "prod"
}

Semantic Versioning

The ~> operator leans on semantic versioning, the MAJOR.MINOR.PATCH contract. A major bump signals breaking changes — removed inputs, renamed outputs, changed behavior. A minor bump adds features backward-compatibly. A patch is a bug fix with no interface change. ~> 6.0 works because SemVer promises 6.x will not break what 6.0 did; the major boundary at 7.0 is where breaking changes are allowed, and that is exactly the line the constraint refuses to cross.

Provider and Module Constraints

There are two places constraints live, and they look slightly different. Provider constraints go in the required_providers block, as a version alongside the source. Module constraints go in the module block as a version argument — but only for Registry-sourced modules. A git or local-path module has no version argument; you pin a git module with ?ref= on a tag instead. Same goal, two mechanisms, depending on where the dependency comes from.

Upgrading Deliberately

terraform init -upgrade re-resolves dependencies to the newest versions your constraints allow and rewrites the lock file. Within a ~> 6.0 constraint that pulls the latest 6.x safely. Crossing a major boundary is different work: raise the constraint to ~> 7.0, read the upgrade guide for the renamed inputs and outputs, run a plan, and review the diff — all as one reviewed change, never a blind bump in a hurry.