Introduction
Terraform 0.14 introduced the dependency lock file which will track the hashes of providers used by the configuration, ensuring the same version of a dependency is installed each time init is performed, even if a loose version constraint is used.
For a detailed overview, including the types of hashing supported, please see the documentation for this feature: https://developer.hashicorp.com/terraform/language/files/dependency-lock
Problem
After upgrading your Terraform version to 0.14, and generating a dependency lock file on a platform, for example your local macOS machine, an init performed on a different platform, for example as a part of a TFE run, produces an error similar to:
Error: Failed to install provider Error while installing hashicorp/aws v3.22.0: the current package for registry.terraform.io/hashicorp/aws 3.22.0 doesn't match any of the checksums previously recorded in the dependency lock file
Cause
When the dependency lock file was generated on the first platform, Terraform recorded the hashes it observed. For a brand new lock file, this is the h1: hash of the platform’s version of the provider, and the zh: hashes of all the versions available when the provider was sourced from the registry.
If the platform that generated the lock file made use of the provider plugin cache
and the cache was already populated with the version that Terraform has determined fulfills the version constraints, the lock file will only contain the h1: hash for the platform’s version of the provider and not include the zh: hashes that the registry supplies.
To confirm this is occurring, check the lock file’s contents.
In this example the lock file was generated on the macOS platform with Terraform selecting the 3.22.0 version of the aws provider already in the provider plugin cache. Terraform recorded the h1 hash of the cached provider but not the zh hashes.
provider "registry.terraform.io/hashicorp/aws" {
version = "3.22.0"
constraints = ">= 3.20.0"
hashes = [
"h1:f/Tz8zv1Zb78ZaiyJkQ0MGIViZwbYrLuQk3kojPM91c=",
]
}
Solution
The Terraform command, providers lock, can be used to update the lock file after consulting the source registries in order to add any new registry supplied hashes to the lock file.
Issuing the command when the lock file only contains the h1 hash of the cached provider:
terraform providers lock
This produces the lock file:
provider "registry.terraform.io/hashicorp/aws" {
version = "3.22.0"
constraints = ">= 3.20.0"
hashes = [
"h1:f/Tz8zv1Zb78ZaiyJkQ0MGIViZwbYrLuQk3kojPM91c=",
"zh:4a9a66caf1964cdd3b61fb3ebb0da417195a5529cb8e496f266b0778335d11c8",
"zh:514f2f006ae68db715d86781673faf9483292deab235c7402ff306e0e92ea11a",
"zh:5277b61109fddb9011728f6650ef01a639a0590aeffe34ed7de7ba10d0c31803",
"zh:67784dc8c8375ab37103eea1258c3334ee92be6de033c2b37e3a2a65d0005142",
"zh:76d4c8be2ca4a3294fb51fb58de1fe03361d3bc403820270cc8e71a04c5fa806",
"zh:8f90b1cfdcf6e8fb1a9d0382ecaa5056a3a84c94e313fbf9e92c89de271cdede",
"zh:d0ac346519d0df124df89be2d803eb53f373434890f6ee3fb37112802f9eac59",
"zh:d6256feedada82cbfb3b1dd6dd9ad02048f23120ab50e6146a541cb11a108cc1",
"zh:db2fe0d2e77c02e9a74e1ed694aa352295a50283f9a1cf896e5be252af14e9f4",
"zh:eda61e889b579bd90046939a5b40cf5dc9031fb5a819fc3e4667a78bd432bdb2",
]
}
Terraform added the zh hashes supplied by the registry while retaining the originally observed h1 hash.
If when running the command you encounter the error:
│ Error: Could not retrieve providers for locking │ │ Terraform failed to fetch the requested providers for linux_amd64 in order to calculate their checksums: some providers could not be installed: │ - registry.terraform.io/hashicorp/aws: the current package for registry.terraform.io/hashicorp/aws 3.22.0 doesn't match any of the checksums previously recorded in the dependency lock file.
Remove the lock file before re-running the command. This issue is caused when the only hash present is a h1 for a different platform than the current one. When attempting to add the zh hashes to the existing lock entry, there needs to be a matching h1 hash for the current platform.
Please note that this example uses a provider sourced from the official Terraform registry, registry.terraform.io. This operation will work for any registry that implements the provider registry protocol.
In-house providers that aren’t available on a registry can be updated similarly, but will require the specifying of either a file system or network mirror. For more details please see: https://developer.hashicorp.com/terraform/cli/commands/providers/lock#lock-entries-for-in-house-providers
For more details including only locking specific platforms, please see the documentation for this command: https://developer.hashicorp.com/terraform/cli/commands/providers/lock
Additional Information
This information applies to all environments where you are running configuration on multiple platforms. In HCP Terraform and Terraform Enterprise instances this will occur, as the environments runs are performed in use the linux_amd64 platform.