Lock File Handling

How to use lock files with Terragrunt

To use OpenTofu/Terraform lock files with Terragrunt, you need to:

1. Run Terragrunt as usual (e.g., run terragrunt plan, terragrunt apply, etc.).
2. Check the .terraform.lock.hcl file into version control.

Everything else with OpenTofu/Terraform and Terragrunt should work as expected. To learn the details of how this works, read on!

How Terragrunt handles lock files

What’s a lock file?

Terraform 0.14 added support for a lock file which gets created or updated every time you run tofu init/terraform init. The file is typically generated into your working directory (i.e., the folder in which you ran tofu init/terraform init) and is called .terraform.lock.hcl. It captures the versions of all the OpenTofu/Terraform providers you’re using. Normally, you want to check this file into version control so that when your team members run OpenTofu/Terraform, they get the identical provider versions.

The problem with mixing remote OpenTofu/Terraform configurations in Terragrunt and lock files

Let’s say you are using Terragrunt with remote OpenTofu/Terraform configurations and you have the following folder structure:

• Directorylive

  • Directoryprod

    • Directoryvpc

      • terragrunt.hcl
  • Directorystage

    • Directoryvpc

      • terragrunt.hcl

Imagine that in live/stage/vpc/terragrunt.hcl, you have the following contents:

live/stage/vpc/terragrunt.hcl

terraform {
  source = "git::git@github.com:acme/infrastructure-modules.git//networking/vpc?ref=v0.0.1"
}

If you ran terragrunt apply in the /live/stage/vpc folder, Terragrunt will:

1. git clone the VPC module in the source URL into a temp folder in .terragrunt-cache/xxx/vpc, where xxx is dynamically determined based on the URL.
2. Run tofu apply/terraform apply in the .terragrunt-cache/xxx/vpc temp folder.

As a result, the .terraform.lock.hcl file will be generated in the .terragrunt-cache/xxx/vpc temp folder, rather than in /live/stage/vpc.

How Terragrunt solves this problem

To solve this problem, since version v0.27.0, Terragrunt implements the following logic for lock files:

1. If Terragrunt finds a .terraform.lock.hcl file in your working directory (e.g., in /live/stage/vpc), before running OpenTofu/Terraform, Terragrunt will copy that lock file into the temp folder it uses when running your OpenTofu/Terraform code (e.g., .terragrunt-cache/xxx/vpc). This way, if you had a lock file checked into version control, Terragrunt will respect and use it with your OpenTofu/Terraform code as you’d expect.
2. After running OpenTofu/Terraform, if Terragrunt finds a .terraform.lock.hcl in the temp folder (e.g., .terragrunt-cache/xxx/vpc), it will copy that lock file back to your working directory (e.g., to /live/stage/vpc). That way, you can commit the lock file (or the changes to the lock file) to version control as usual.

<!— markdownlint-disable MD026 —>

Check the lock file in!

After running Terragrunt on each of your modules, you should check your lock files in! That means your folder structure should end up looking something like this:

• Directorylive

  • Directoryprod

    • Directoryvpc

      • .terraform.lock.hcl
      • terragrunt.hcl
  • Directorystage

    • Directoryvpc

      • .terraform.lock.hcl
      • terragrunt.hcl

Also, any time you change the providers you’re using, and re-run init, the lock file will be updated, so make sure to check the updates into version control too.

Disabling the copy of the generated lock file

In certain use cases, like when using a remote module containing a lock file within it, you probably don’t want Terragrunt to also copy the lock file into your working directory. In these scenarios, you can opt out of copying the .terraform.lock.hcl file by using copy_terraform_lock_file = false in the terraform configuration block as follows:

terragrunt.hcl

terraform {
  ...
  copy_terraform_lock_file = false
}