Provider Version Constraints and Upgrades

A provider version constraint is the production control for provider supply chain. A pinned version is reproducible. An unpinned version can change without notice. The lesson teaches the constraint syntax, the lock file, and the upgrade procedure.

The version constraint

The required_providers block constrains the provider version:

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

Operators:

• = 5.0.0 — exact version.
• >= 5.0.0 — at least 5.0.0.
• ~> 5.0 — compatible release (5.0.x, 5.1.x, 5.2.x, but not 6.0.x).
• ~> 5.0.0 — exact patch (5.0.0, 5.0.1, 5.0.2, but not 5.1.0).
• >= 5.0, < 6.0 — range.

The courses recommendation: use ~> 5.0 or >= 5.0, < 6.0.

The dependency lock file

The .terraform.lock.hcl file records the resolved version:

# This file is maintained automatically by "terraform init".
# Manual edits may be lost - proceed with caution!

provider "registry.terraform.io/hashicorp/aws" {
  version = "5.0.0"
  hashes = [
    "h1:abc123...",
    "zh:def456...",
  ]
}

The lock file records:

• The exact version of each provider.
• The hashes of the provider binary, verified against the registry.

The lock file is the reproducibility contract. The CI pipeline, the developers workstation, and the production apply should all use the same lock file.

The lock file in Git

The lock file should be committed to Git:

.terraform/
.terraform.lock.hcl  ← commit this
terraform.tfstate
terraform.tfstate.backup
*.tfplan

The lock file is the source of truth for the provider version. The configuration is the source of truth for the constraint.

Upgrading providers

An upgrade is a managed change:

# 1. Update the constraint
vim versions.tf

# 2. Update the lockfile
terraform init -upgrade

# 3. Verify the plan matches the expectation
terraform plan

# 4. Apply
terraform apply

The init -upgrade:

• Downloads the new provider version.
• Updates the lockfile.
• Does not modify the configuration.

The plan may show changes due to provider schema updates. The plan is the audit trail.

The provider upgrade failure modes

The failure modes:

Schema changes. The new provider version may have a new schema for an existing resource. The plan may propose changes that are not in the configuration.

Default changes. The new provider version may have new defaults for an attribute. The plan may propose changes based on the new defaults.

Removal. The new provider version may remove a resource type. The plan fails with an error.

Authentication. The new provider version may have a new authentication method. The apply fails.

The fix is to read the release notes before the upgrade. The release notes document the changes.

The multi-platform lock file

The lock file can record hashes for multiple platforms:

provider "registry.terraform.io/hashicorp/aws" {
  version = "5.0.0"
  hashes = [
    "h1:abc123...",  # linux_amd64
    "h1:def456...",  # darwin_amd64
    "h1:ghi789...",  # darwin_arm64
  ]
}

The multi-platform lock file is appropriate for teams with heterogeneous workstations (Linux + macOS).

The CI pipeline uses a single platform. The lock file includes hashes for the CI platform and the workstation platforms.

The rejected practice

A rejected practice is to use unpinned providers:

required_providers {
  aws = {
    source = "hashicorp/aws"
    # No version constraint
  }
}

The unpinned constraint is the production antipattern. The provider version can change without notice. The plan may propose unexpected changes.

The courses recommendation: always pin the version.

What comes next

The next lesson is provider authentication — how to configure credentials securely.

Verification