HandsOnAzure

Pin, Don't Freeze: A Terraform Version Strategy That Won't Leave You Stranded

On this page
  1. Half one: pin everything, and commit the lockfile
  2. Half two: automate the upgrades so the pins don’t ossify
  3. Surviving the major-version jump
  4. The one-sentence version

Every team hits this tension eventually.

Pin your Terraform version and your provider versions, and you get reproducibility: the same code produces the same plan on every machine and every pipeline run. Good. But months pass, you never touch the versions because touching them is scary, and one day you need a new resource argument that only exists in a provider three major versions ahead of where you froze. Now you are doing a terrifying multi-version jump under deadline pressure.

Don’t pin, and every terraform init is a small gamble. A provider releases a breaking change on a Tuesday and your Wednesday pipeline fails for reasons that have nothing to do with your code.

The mistake is treating this as a single decision, pin or don’t pin. It is not a decision, it is a system with two halves: pin hard for reproducibility, and automate the upgrades so you never fall behind. Each half is useless without the other.

Half one: pin everything, and commit the lockfile

Three layers of pinning, each doing a different job.

Pin Terraform itself so a teammate on a newer CLI cannot silently rewrite your state:

terraform {
  required_version = "~> 1.9.0"
}

Pin providers with a pessimistic constraint, allowing patch and minor updates within a major, never an automatic major jump:

terraform {
  required_providers {
    azurerm = {
      source  = "hashicorp/azurerm"
      version = "~> 4.20"
    }
  }
}

~> 4.20 means “any 4.x at or above 4.20, but never 5.0.” The major-version boundary is where AzureRM puts its breaking changes, so this is the line you never want crossed by accident.

Commit .terraform.lock.hcl. This is the part teams skip, and it is the one that actually delivers reproducibility. The version constraints above describe a range; the lockfile records the exact versions and their checksums that were last selected. Commit it, and everyone, every laptop and every CI run, resolves to the identical provider build.

Then enforce it in CI so the pipeline can never quietly upgrade:

terraform init -lockfile=readonly

If the configuration needs a provider version the lockfile does not allow, init fails instead of silently pulling something new. In CI, that is exactly the behaviour you want: the pipeline is not allowed to make version decisions.

Half two: automate the upgrades so the pins don’t ossify

Pinning without a refresh mechanism is just slow-motion legacy. The second half is a scheduled upgrade lane that proposes version bumps on a cadence, runs them through your normal checks, and lets you promote deliberately.

Use Renovate or Dependabot to open pull requests when new Terraform, provider, or module versions are released. Renovate is the stronger choice for Terraform: it understands required_providers, module sources, and the lockfile, and it can group updates and respect your ~> constraints.

A minimal renovate.json that separates safe from risky:

{
  "extends": ["config:recommended"],
  "terraform": { "enabled": true },
  "packageRules": [
    {
      "matchManagers": ["terraform"],
      "matchUpdateTypes": ["minor", "patch"],
      "groupName": "terraform minor/patch",
      "schedule": ["before 9am on monday"]
    },
    {
      "matchManagers": ["terraform"],
      "matchUpdateTypes": ["major"],
      "labels": ["breaking-change-review"],
      "dependencyDashboardApproval": true
    }
  ]
}

Minor and patch updates get grouped into a weekly PR you can merge with a glance. Major updates require explicit approval before Renovate even opens the PR, because a major AzureRM bump is a project, not a merge.

The crucial point: each of these PRs runs your existing CI. It refreshes the lockfile, runs terraform plan, runs your security scans. You are not upgrading blind; you are reading a real plan diff against a non-production workspace before anything reaches production. The bot does the tedious part (noticing the release, refreshing the lockfile); you keep the judgment (reading the changelog, reading the plan).

Surviving the major-version jump

When the major bump does come, and with AzureRM it comes roughly yearly, the lockfile-plus-bot system makes it survivable instead of heroic:

  1. Let the upgrade PR refresh the lockfile against the new major
  2. Read the provider’s upgrade guide: AzureRM publishes one per major version listing renamed arguments, removed resources, and changed defaults
  3. Run terraform plan in a throwaway or dev workspace and read every line, because major bumps often surface as unexpected diffs even when your config is “correct”
  4. Fix the config, get a clean plan, then promote the same lockfile up through your environments

Because you were never more than a few minor versions behind, the changelog you have to read is short. That is the whole reward for running the upgrade lane: you trade one annual terrifying jump for a steady drip of boring, reviewable updates.

The one-sentence version

Pin for reproducibility, automate for freshness. The lockfile and the upgrade bot are two halves of the same strategy, and running only one of them is the actual mistake.

The lockfile alone leaves you frozen. The bot alone (without committed locks) leaves you unreproducible. Together, your builds are deterministic and you are never more than a week behind the ecosystem.