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?
3 Answers
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.
-
5There 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– spuderCommented Nov 10, 2021 at 1:04
-
7What about when you are using Terraform Cloud? Would it not be needed in that case? 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.– blambCommented Sep 12, 2022 at 16:49
-
1You 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
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.
-
Notes about resolving this here: Should terragrunt-generated files be added to source control? Commented Nov 18, 2023 at 23:04
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
-
1True, 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
.lock
files for other languages.