⚡ ~/naveed Interview Prep
⚡ Portfolio Home 👤 About Naveed Bio & Credentials 📫 Contact Naveed Get In Touch ✍️ Engineering Blog Deep Dives 🎯 Interview Hub 1,000+ Scenarios ☸️ Kubernetes Mastery Hub 24 Modules 🎮 DevOps Arcade & Quizzes Subnet Blitz ⚡ 🗺️ DevOps Roadmaps PDFs & Guides 🤖 Morpheus Analysis AI Quant ↗ 🛠️ Developer Tools Utilities 🧪 Labs & Experiments 📄 Interactive CV & Certs 🔗 All Links & Socials ⚡ Join The Dispatch (Weekly SRE Newsletter) →
← Back to All Terraform & IaC Interview Questions Scenario 36 of 120 in Terraform & IaC
Senior DevOps / SRE [L2] Terraform Terraform Modules & State Production Scenario [L2]
🎯 Target Role / Context: Terraform Scenario #31 (L2) · Use VPC ID from another module

Q: What is the `.terraform.lock.hcl` file and should you commit it?

The .terraform.lock.hcl file is Terraform's dependency lock file: it records the exact provider versions and package checksums selected by terraform init, and yes, you should commit it to version control.

#Terraform #L2 #IaC #Cloud Infrastructure
🎙️ Candidate Opening & Architectural Context
"The <code>.terraform.lock.hcl</code> file is Terraform's dependency lock file: it records the exact provider versions and package checksums selected by <code>terraform init</code>, and yes, you should commit it to version control. Interviewers ask because an uncommitted lock file means every laptop and CI runner can resolve a different provider version inside the same <code>version</code> constraint, which turns a routine plan into a surprise diff. A strong answer explains what the file contains, what it does not cover (modules), how hashes interact with multiple platforms, and how to upgrade deliberately through a reviewed pull request."
Advertisement
⚡ Recommended Practice Lab

Want to master this scenario in a live sandbox? KodeKloud's HashiCorp Certified Terraform Associate (003) Interactive Labs covers this exact problem with hands-on terminal drills.

🛠️ Production Runbook & Step-by-Step Resolution

Direct Answer: The <code>.terraform.lock.hcl</code> file is Terraform's dependency lock file: it records the exact provider versions and package checksums selected by <code>terraform init</code>, and yes, you should commit it to version control. Interviewers ask because an uncommitted lock file means every laptop and CI runner can resolve a different provider version inside the same <code>version</code> constraint, which turns a routine plan into a surprise diff. A strong answer explains what the file contains, what it does not cover (modules), how hashes interact with multiple platforms, and how to upgrade deliberately through a reviewed pull request.

1️⃣

What the .terraform.lock.hcl file records

Think of it as a package-lock for providers: constraints say what is allowed, the lock file says what was chosen.

# .terraform.lock.hcl (generated, do not hand-edit)
provider "registry.terraform.io/hashicorp/aws" {
  version     = "5.31.0"
  constraints = "~> 5.0"
  hashes = [
    "h1:...",
    "zh:...",
  ]
}
  • Contents: one provider block per provider with the selected version, the original constraints, and a set of hashes (h1: and zh: entries) used to verify the downloaded package.
  • Created by: terraform init when no entry exists for a provider. Later runs reuse the recorded version as long as it still satisfies the configuration.
  • Constraints vs lock: version = "~> 5.0" in required_providers permits many releases; the lock file pins exactly one of them until you ask for an upgrade.
  • Not covered: modules are not locked by this file. Pin them with an explicit version argument for registry modules or a git ref for git sources.
2️⃣

Hands-on: should you commit the .terraform.lock.hcl file

Commit it to the root module directory alongside your .tf files, and keep the .terraform/ directory ignored.

# first-time setup
terraform init
git add .terraform.lock.hcl
git commit -m "Pin provider selections"

# confirm it is tracked and not ignored
git check-ignore -v .terraform.lock.hcl || echo "not ignored: good"
git ls-files .terraform.lock.hcl
  • Commit: check that .gitignore contains .terraform/ but not .terraform.lock.hcl. Many generic Terraform gitignore templates were historically wrong about this.
  • Why: it gives reproducible provider selection across developers, CI and production applies, and it detects a tampered or substituted provider package through checksum mismatch.
  • Review it: a lock file change in a pull request is a provider upgrade. Reviewers should read the release notes, not just the hash noise.
  • Reusable modules: a child module that is never run on its own does not need its own lock file; the root module that runs init owns it.
Advertisement
3️⃣

Upgrading providers and covering every platform

Upgrades are explicit, and the file must carry hashes for every OS and architecture that runs Terraform.

terraform init -upgrade

terraform providers lock \
  -platform=linux_amd64 \
  -platform=linux_arm64 \
  -platform=darwin_arm64

# CI: refuse to modify the lock file
terraform init -lockfile=readonly
  • Upgrade deliberately: terraform init -upgrade re-resolves versions within your constraints and rewrites the lock file; commit the result in its own PR.
  • Multi-platform hashes: if developers use macOS arm64 and CI uses Linux amd64, run terraform providers lock with every -platform so the file holds hashes for all of them.
  • Read-only in CI: terraform init -lockfile=readonly fails if init would need to change the lock file, which catches a forgotten commit.
  • Inspect: terraform providers shows which providers each module requires and terraform version lists the selected versions.
4️⃣

Failure modes and how to fix them

Most lock file incidents are checksum mismatches or constraints that no longer match the recorded version.

  • Checksum mismatch: the error says the package "doesn't match any of the checksums previously recorded in the dependency lock file". It usually means the file only holds hashes for another platform; regenerate with terraform providers lock for all platforms.
  • Constraint conflict: if you raise the constraint above the locked version, init reports that the locked version does not match; run terraform init -upgrade.
  • Merge conflicts: resolve by picking one side, then re-running init (or providers lock) so the file is regenerated rather than hand-merged.
  • Mirrors: when using a provider mirror or private registry, hashes can differ from the public registry. Generate the lock file using the same installation source your CI uses.
  • Hash types: zh: hashes cover the zipped release package as published, while h1: hashes cover the unpacked contents and work across mirrors, which is why both appear.
Pro Tip: Never delete the lock file to "fix" an error without understanding why: you silently allow the next init to pick newer provider versions and change your plan.
5️⃣

Automating lock file hygiene

Treat provider upgrades as a routine, reviewed dependency update.

  • Automated PRs: Renovate and Dependabot can open pull requests that bump providers and refresh .terraform.lock.hcl; confirm your tool regenerates hashes for all platforms you use.
  • Plan on the PR: run terraform plan in CI for the upgrade PR so provider behavior changes appear as a visible diff before merge.
  • Supply chain: checksum verification plus pinned versions reduces the risk of a different package being installed than the one you reviewed.
💡 The Senior SRE Gold Nugget (Key Architectural Takeaway)
"Pro-Tip: Commit <code>.terraform.lock.hcl</code>, generate hashes for every platform with <code>terraform providers lock</code>, and use <code>init -lockfile=readonly</code> in CI so provider upgrades only happen through a reviewed PR."
⚡ 60-Second Elevator Pitch Talking Points
  • The .terraform.lock.hcl file pins the exact provider versions and checksums chosen by terraform init, so it belongs in version control.
  • I verify with git diff on the file and terraform providers, and run init with -lockfile=readonly in CI.
  • I automate upgrades with Renovate or Dependabot PRs and refresh hashes for linux and darwin platforms.
⛔ Critical Candidate Mistakes to Avoid in This Scenario

Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:

  1. Adding .terraform.lock.hcl to .gitignore Each machine then resolves its own provider version, and plan results differ between laptops and CI.
  2. Generating the lock file only on macOS It will lack hashes for linux_amd64, so the CI runner fails with a checksum mismatch.
  3. Deleting the lock file to clear an error Terraform will select the newest allowed provider and may introduce unreviewed behavior changes.
  4. Assuming the lock file pins modules It only covers providers; modules need their own version or git ref pinning.
Advertisement
Want more Terraform & IaC scenarios?
Explore our complete collection of scenario-based Terraform & IaC interview runbooks.
Browse All Terraform & IaC Questions →