227

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?

9
  • 37
    It should be committed: it's needed to keep versions of plugins in sync.
    – zerkms
    Commented Jun 14, 2021 at 0:58
  • 1
    Privacy seems like a strange criterion. For me, the reason for .gitignore is that there are files (editor temporaries, backups, build output, generated source) that I do not want to be retained in the repo.
    – iggy
    Commented Jun 14, 2021 at 0:58
  • 1
    My concern is both privacy and unwanted files in the repo in general.
    – engineer-x
    Commented Jun 14, 2021 at 1:00
  • 3
    Since i have not enough reputation, i´m not able to just comment. Like zerkms said, this should be commited for the plugin sync. Treat it like package.lock (or similiar for other languages... composer.lock, cargo-lock...)
    – pfandie
    Commented Jun 14, 2021 at 7:19
  • This is completely based on your team's workflow and collaboration style, and also on the ranges you specify in your provider versions. If the versions are expansive, then you probably should commit it. If the team is less hands on, then also you should probably commit it. It would be the same reasoning behind other .lock files for other languages. Commented Jun 14, 2021 at 12:23

3 Answers 3

259

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.

5
  • 5
    There are some special considerations if you have multiple people on a team who are using mac/linux/windows and you attempt to share a single lock file github.com/hashicorp/terraform/issues/28041
    – spuder
    Commented Nov 10, 2021 at 1:04
  • 7
    What about when you are using Terraform Cloud? Would it not be needed in that case?
    – paradroid
    Commented Dec 12, 2021 at 16:07
  • what about when you are using a team, and there is merge conflicts, due to records in the lock file being merged that may conflict. e.g. is it safe to just merge the file, do you keep the newest entrys? I guess its more complicated than that, e.g. if somebody has ovewritten code, you would need to identify whats changed, causing the need to now inspect and maybe edit the file, which sounds horrific.
    – blamb
    Commented Sep 12, 2022 at 16:49
  • 1
    You should not merge the lock file. In the post the documentation states Terraform updates it everytime tf init is run. Treat it like a binary file similar to an image - you wouldn't try to merge that. Commented Dec 20, 2022 at 21:55
  • I ran into a unique scenario where the repository I checked out contained a lock file. I'm not aware of what architectures the group was working on, but I know that M1 Macs run into issues, especially on older versions of Terraform. I kept running into errors, I later figured out I needed to delete the lock file in the repository and do a terraform init. I also had to use terraform providers lock -platform=darwin_amd64 to prevent terraform from checking out darwin_arm64 Even though the project I'm working on has a lock file, my work around is to delete it and not commit the delete. Commented Oct 25, 2023 at 21:19
10

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.

1
4

You can also execute the following command to establish with platforms are present in your environment:

terraform providers lock -platform=darwin_amd64 -platform=darwin_arm64 -platform=linux_amd64
1
  • 1
    True, but even then it can cause problems with certain plugins. I wasn't able to get it stable even by running this statement locally and find this also quite a burden to do each time. On their documentation it states that an init should actually pull all available hashes of a provider by default, but I never saw this working, on Windows only got Windows. We are also going to exclude the lock files now, but a nicer work-around is when you only remove the 'hashes' part from the lock file, then you can keep the version part and it will also work. Commented Mar 13, 2023 at 13:49

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.