When working with Terraform, one common question that arises is whether to include the .terraform.lock.hcl file in the Git repository or leave it out by adding it to .gitignore. This decision impacts the version control practices and reproducibility of your infrastructure deployments. In this article, we’ll explore the contents of the .terraform.lock.hcl file, discuss why it’s typically excluded from version control, and provide guidance on what to add to the .gitignore so it doesn’t get committed to your Git repository.

What is the .terraform.lock.hcl file?

The .terraform.lock.hcl (or Terraform Dependency Lock File) file is a generated file created when running terraform commands during the Terraform Workflow Process. It’s purpose is to lock down the versions of modules and Terraform providers used within the Terraform project configuration. It serves as a snapshot of the exact versions of dependencies (modules and providers) required for the Terraform project. This is so future executions of terraform commands are able to read what the projects dependencies are from previous runs.

When you run terraform init in a directory containing a HashiCorp Terraform project or configuration, Terraform checks for the presence of the .terraform.lock.hcl file. If the file is not present, Terraform resolves the module and provider dependencies based on the version constraints specified in the configuration files (like required_providers and module blocks). It then generates the .terraform.lock.hcl file to save these resolved dependency versions.

What does .terraform.lock.hcl file look like?

The .terraform.lock.hcl file typically contains entries for:

• Required Terraform Providers – The source and version of each Terraform provider used in the configuration project.
• Modules – The source and version of each module used in the configuration.

Let’s take a look at what the contents of this file might look like:

# This file is maintained automatically by "terraform init".
# Manual edits may be lost in future updates.

provider "registry.terraform.io/hashicorp/azurerm" {
  version     = "3.84.0"
  constraints = ">= 3.0.0"
  hashes = [
    "h1:y/NWRLvnJmyJ5lf/AnLFy25jfyJqp6xwwxLxZnvovAs=",
    "zh:14a96daf672541dbc27137d9cc0a96a737710597262ecaaa64a328eb1174e5df",
    "zh:16d8e794fdd87ed8e64291fe8a617f420d8263f21672033333a020d06f4c9618",
    "zh:64e5cd1bb6a81bccffff0d1f77790286ab46179cf12442134c3f3bca722afc1b",
  ]
}

As you can see, the lock file specifies the required providers and modules along with their versions. While this information is crucial for ensuring consistent deployments, the file itself is considered a generated artifact and is not typically meant to be manually edited.

In this example:

• The azurerm provider is specified.
• The source attribute indicates the source of the provider, which is "registry.terraform.io/hashicorp/azurerm".
• The version attribute specifies the version of the provider, which is "3.84.0".
• The constraints defines when upgrading the provider that the version should be restricted to the latest revision of version 3.x.x.

This lock file ensures that when you run Terraform commands, such as terraform init, the specified version of the azurerm provider will be used, providing consistency and predictability in your infrastructure deployments.

How .terraform.lock.hcl Relates to Deployment Pipelines?

When implementing the Terraform Workflow Process and setting up a DevOps workflow for managing Infrastructure deployments using HashiCorp Terraform, a separate version of the .terraform.lock.hcl file will be saved within the artifacts for each environment.

When maintaining the consistency and predictability of each environment deployment (such as Production, Stage, Test, Development, etc) it’s important to maintain the Terraform dependencies of that specific environment. This becomes important when upgrading to a newer version of a Terraform provider or other Terraform dependency, since that upgrade will generally be done starting in Development environments then going to Stage, Test, etc. before pushing that change to Production.

By omitting the Terraform Dependency Lock file (.terraform.lock.hcl) from Git or other source control repositories, then clean, consistent, and predictable deployments can be maintained across all the various environments managed using the Terraform project. Because of this, the best practice is to add the .terraform.lock.hcl file to .gitignore to configure Git to ignore the file on future commits to the repository.

Additionally, keeping .terraform.lock.hcl out of source control will help eliminate any dependency conflict issues between multiple environment deployments managed by the Terraform project.

This applied just the same whether you’re using an Microsoft Azure Storage Account or Amazon S3 to store the Terraform state and lock files in the cloud, or even using HashiCorp’s Terraform Cloud service to manage Terraform deployments.

What to Add to .gitignore

To prevent the .terraform.lock.hcl file from being committed to the Git repository, it’s best practice to add it to the .gitignore. This ensures that Git will ignore the file, and the file will remain local to each user’s environment and doesn’t clutter the repository with unnecessary generated artifacts.

Here’s how you can add the .terraform.lock.hcl file to your .gitignore:

# Ignore Terraform lock file
.terraform.lock.hcl

By adding this line to your .gitignore, you instruct Git to ignore any changes to the lock file and prevent it from being included in version control. So when git add is run, it will no include the .terraform.lock.hcl file in the staged changes to be committed to the Git repository.

Conclusion

It’s best practice to add the .terraform.lock.hcl (Terraform Dependency Lock) file to .gitignore so it’s omitted from your Git repository commits. This approach helps maintain a clean and focused Git repository while still ensuring reproducibility and consistency in your Terraform deployments; regardless of where the Terraform state and lock files are stored, or even the method of how the Terraform deployment pipelines are instrumented from Azure DevOps and GitHub Actions, to HashiCorp’s Terraform Cloud.

About the Author