Terraform Best Practices

Chapter 2 · Practice 2 of 4

Commit .terraform.lock.hcl and upgrade providers on purpose

From Versions and dependencies

Why it matters

The dependency lock file records the exact provider versions Terraform selected and the checksums of their packages. The Terraform docs recommend committing it, so provider changes go through code review like any other change.

How it behaves:

  • terraform init reuses the versions in the lock file, even when newer ones match your constraints.
  • terraform init -upgrade picks the newest allowed versions and updates the file.
  • Checksums are recorded only for the platform that ran init. If the team uses macOS and CI uses Linux, run terraform providers lock with each -platform so both are covered.

To check, run git ls-files .terraform.lock.hcl in each root module. No output means the file is not committed.

Example

Shell
terraform init -upgrade
terraform providers lock \
  -platform=linux_amd64 \
  -platform=darwin_arm64
git add .terraform.lock.hcl