Provider Version Constraints

Providers evolve fast. The AWS provider ships a release most weeks, tracking new AWS services and arguments almost as they land, and every few quarters it cuts a major version that carries breaking changes — renamed arguments, removed attributes, altered defaults. Constraining the provider version in required_providers is what keeps an init from silently pulling a breaking 7.0 into a config written for 6.x.

This is the same version-constraint syntax modules use, applied to the most volatile dependency in your project. The AWS provider changes far more often than Terraform core does, so the constraint here earns its keep more than almost anywhere else in the config.

Declaring Provider Constraints

The constraint lives in the required_providers block inside the terraform block. Each provider names its source — the registry address, hashicorp/aws — and a version constraint. The source is not optional cosmetics: without it Terraform guesses the namespace, which breaks for any non-HashiCorp provider and produces confusing init errors.

terraform {
  required_version = "~> 1.13"

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 6.0"
    }
  }
}

Why AWS Provider Versions Matter

The AWS provider's release cadence is its own argument for pinning. A new release most weeks means an unconstrained init can pull a different version on Tuesday than it did on Monday. New AWS resources arrive tied to specific provider versions, so the feature you need may require a bump — and a major version drops support for arguments your config still uses. Both directions, too old and too new, are real risks, which is why the constraint sets a range rather than chasing latest.

The Pessimistic Constraint for Providers

The ~> operator — the pessimistic constraint — is the right tool here. ~> 6.0 allows any 6.x release, so you take patches and new minors automatically, but it refuses 7.0 and the breaking changes a major version brings. You get bug fixes and new resources within 6.x without an unreviewed jump across the major-version boundary that would land renamed or removed arguments on you mid-sprint.

# version = "~> 6.0"
# 6.31.0  -> allowed   (a 6.x minor)
# 6.99.1  -> allowed   (still within 6.x)
# 7.0.0   -> blocked   (breaking major, needs a reviewed bump)

Upgrading the Provider

A major version bump is a deliberate, reviewed change, not a side effect of running init. Read the provider's upgrade guide first — it lists the renamed and removed arguments — then widen the constraint to the new major, run init -upgrade to move the lock, and read the resulting plan carefully for replacements before applying. Treating the bump as a normal PR, with the plan attached, is what keeps a 6-to-7 move from breaking production by surprise.

# 1. read the v7 upgrade guide on the registry
# 2. widen the constraint:  version = "~> 7.0"
# 3. rewrite the lock within the new range
terraform init -upgrade
# 4. review the plan for renamed args and replacements
terraform plan

required_version vs Provider Version

Two separate constraints guard two separate things. required_version pins Terraform core — the binary that runs the plan — and the provider's version pins the AWS plugin. Constraining only the provider leaves core version skew in place, where one teammate runs 1.7 and another 1.9 and a state file gets written by a version others cannot read. Pin both, in the same terraform block, so the whole team and CI run identical core and identical provider.