Should .terraform.lock.hcl be included in the .gitignore file?

Question

From my current knowledge, there is no reason .terraform.lock.hcl should be included in the .gitignore. Nothing about this file is private, or is there?

Answer 1

Per the Terraform documentation on the Dependency Lock File:

Terraform automatically creates or updates the dependency lock file each time you run the terraform init command. You should include this file in your version control repository so that you can discuss potential changes to your external dependencies via code review, just as you would discuss potential changes to your configuration itself.

The key to understanding why you should commit that file is found in the following section on Dependency Installation Behavior:

When terraform init is working on installing all of the providers needed for a configuration, Terraform considers both the version constraints in the configuration and the version selections recorded in the lock file.

If a particular provider has no existing recorded selection, Terraform will select the newest available version that matches the given version constraint, and then update the lock file to include that selection.

If a particular provider already has a selection recorded in the lock file, Terraform will always re-select that version for installation, even if a newer version has become available. You can override that behavior by adding the -upgrade option when you run terraform init, in which case Terraform will disregard the existing selections and once again select the newest available version matching the version constraint.

Essentially this is intended to have Terraform continue to use the version of the provider selected when you added it. If you do not checkin the lock file, you will always be automatically upgraded to the latest version that obeys the constraint in code, which could lead to unintended consequences.

Note: You can force Terraform to upgrade when doing the init call by passing the -upgrade flag.

terraform init -upgrade

Update for Cross-Platform Development

From the Terraform documentation on the providers lock command:

Specifying Target Platforms In your environment you may, for example, have both developers who work with your Terraform configuration on their Windows or macOS workstations and automated systems that apply the configuration while running on Linux.

In that situation, you could choose to verify that all of your providers support all of those platforms, and to pre-populate the lock file with the necessary checksums, by running terraform providers lock and specifying those three platforms:

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

The above example uses Unix-style shell wrapping syntax for readability. If you are running the command on Windows then you will need to replace the backslashes with carets (for cmd) or backticks (for PowerShell).

So you should still check the lock file into version control, but you should ensure the lock file contains the checksums for providers on all platforms.

Answer 2

I think the above advice is only useful if your source control repository is being used by a homogenous set of engineers and/or a single engineer. On a large heterogenous group, it will fail with the following error:

│ Error: Failed to install provider
│
│ Error while installing hashicorp/null v3.1.1: the local package for registry.terraform.io/hashicorp/null 3.1.1 doesn't match any of the checksums previously recorded in the dependency lock file
│ (this might be because the available checksums are for packages targeting different platforms)

To solve that error, delete the .terraform.lock.hcl file, and re-initalise. It will regenerate the file for your own workstation.

I am willing to entertain that we're doing it wrong, but at least in our case, we need to add this to .gitignore, or every time one engineer makes a commit, all engineers using a different OS will get this error and have to terraform init again.