Terraform Lock File Management

Problem

Introduction

Terraform 0.14 and later use a lock file (.terraform.lock.hcl) to ensure that every member of a team uses the same provider versions. This file records the specific versions of providers used in your configuration, allowing for consistent and repeatable runs across different environments. The lock file is essential to Terraform's operation, even if it is not retained or distributed.

Terraform automatically generates this file during the terraform init command if one does not already exist.

Approaches to Managing the Lock File

Teams typically adopt one of two approaches for managing the .terraform.lock.hcl file, depending on their workflow and collaboration needs.

Approach 1: Ignoring the Lock File

One approach is to allow each team member and system to generate its own lock file. This method is similar to the behavior of Terraform versions before 0.14.

To ignore the Terraform lock file when collaborating with a team, add .terraform.lock.hcl to the repository's .gitignore file. Doing so prevents the distribution of the lock file to other team members. Each person, CI system, and instance of HCP Terraform or Terraform Enterprise that executes terraform init creates a new lock file for its own use.

Approach 2: Distributing a Central Lock File

Another approach is to create and distribute a single lock file to ensure that all team members and automation systems standardize on the same provider versions. This requires generating a lock file that is compatible with all platforms where the configuration will run.

First, generate the lock file by running the terraform init command. The resulting .terraform.lock.hcl file will contain checksums for the provider on your current platform, as well as checksums for all other platforms that the provider supports.

For example, after running terraform init on macOS for a configuration that uses the hashicorp/null provider, you can view the contents of the lock file.

Execute the cat command to display the file's contents.

$ cat .terraform.lock.hcl

The output shows the provider version and a list of hashes for all available platform releases.

# This file is maintained automatically by "terraform init".
# Manual edits may be lost in future updates.
provider "registry.terraform.io/hashicorp/null" {
  version = "3.1.0"
  hashes = [
    "h1:xhbHC6in3nQryvTQBWKxebi3inG5OCgHgc4fRxL0ymc=",
    "zh:02a1675fd8de126a00460942aaae242e65ca3380b5bb192e8773ef3da9073fd2",
    "zh:53e30545ff8926a8e30ad30648991ca8b93b6fa496272cd23b26763c8ee84515",
    "zh:5f9200bf708913621d0f6514179d89700e9aa3097c77dac730e8ba6e5901d521",
    "zh:9ebf4d9704faba06b3ec7242c773c0fbfe12d62db7d00356d4f55385fc69bfb2",
    "zh:a6576c81adc70326e4e1c999c04ad9ca37113a6e925aefab4765e5a5198efa7e",
    "zh:a8a42d13346347aff6c63a37cda9b2c6aa5cc384a55b2fe6d6adfa390e609c53",
    "zh:c797744d08a5307d50210e0454f91ca4d1c7621c68740441cf4579390452321d",
    "zh:cecb6a304046df34c11229f20a80b24b1603960b794d68361a67c5efe58e62b8",
    "zh:e1371aa1e502000d9974cfaff5be4cfa02f47b17400005a16f14d2ef30dc2a70",
    "zh:fc39cc1fe71234a0b0369d5c5c7f876c71b956d23d7d6f518289737a001ba69b",
    "zh:fea4227271ebf7d9e2b61b89ce2328c7262acd9fd190e1fd6d15a591abfa848e",
  ]
}

When this configuration runs on another platform, the version will be required and the provider must be signed with the same signature. Terraform then verifies that the downloaded provider matches one of the recorded hashes, ensuring version consistency.

Updating the Lock File

When you need to update a provider version or add a new provider, you can update the lock file by running one of the following commands:

• To upgrade to the latest acceptable version of a provider, use terraform init -upgrade.
• To add a new provider, run terraform init.
• To regenerate the file from scratch, remove the current contents of the .terraform directory and the .terraform.lock.hcl file, then run terraform init again.

Additional Information

• For a step-by-step guide, refer to the Lock and Upgrade Provider Versions tutorial.
• For more details on managing provider dependencies, see the Terraform providers lock command documentation.