Terraform v0.14+ dependency lock file (.terraform.lock.hcl) gotchas

UPD: 1, 2 are still relevant for newer versions (0.15, 1.x)

In December 2020 a new version of Terraform was released — v0.14. Along with many new things there was released a pretty nice feature — Provider Dependency Lockfile. It will help you to verify provider binary authenticity and ensure that all environments will use not only the same provider version, but binary will be the same as well.

Unfortunately, so far this feature is pretty new and there are some gotchas that it’s good to keep in mind:

1. terraform init will create a new file named .terraform.lock.hcl during the run if it doesn’t exist. But it will be created only for current architecture. It means that if you’re using macOS as development environment, but Linux in CI, terraform commands in CI will fail with error “the current package for ‘provider’ doesn’t match any of the checksums previously recorded in the dependency lock file”. So, if you want to avoid that, you have to manually run terraform providers lock with required architectures, for example for macOS and Linux: terraform providers lock -platform=linux_amd64 -platform=darwin_amd64 . You can check how many architectures are in lock file by amount of lines, starting with “h1:” in hashes[] array.
2. Another pretty annoying thing — is that when you have provider cache enabled (either with TF_PLUGIN_CACHE_DIR env variable or command line options), you will get full lock file only when provider hasn’t cached yet. In other cases lock file will contain only “h1:” type hashes (check 3rd example below). In general it won’t cause problems, but in other environments lock file will be updated. You can avoid that by unsetting TF_PLUGIN_CACHE_DIR during lock file creation.
3. Fixed in 0.14.5. On all platforms, with exception for Windows probably, lock file is created with +x permissions (777 on local fs and commited to git with 755). You can check this issue for details, because most likely you’ll have weird diffs with this file changes, when just permissions will be changed with no reason.

P.S. Examples of different lock files:

All hashes, but only one platform

# This file is maintained automatically by "terraform init".
# Manual edits may be lost in future updates.
provider "registry.terraform.io/hashicorp/null" {
  version = "3.0.0"
  hashes = [
    "h1:V1tzrSG6t3e7zWvUwRbGbhsWU2Jd/anrJpOl9XM+R/8=",
    "zh:05fb7eab469324c97e9b73a61d2ece6f91de4e9b493e573bfeda0f2077bc3a4c",
    "zh:1688aa91885a395c4ae67636d411475d0b831e422e005dcf02eedacaafac3bb4",
    "zh:24a0b1292e3a474f57c483a7a4512d797e041bc9c2fbaac42fe12e86a7fb5a3c",
    "zh:2fc951bd0d1b9b23427acc93be09b6909d72871e464088171da60fbee4fdde03",
    "zh:6db825759425599a326385a68acc6be2d9ba0d7d6ef587191d0cdc6daef9ac63",
    "zh:85985763d02618993c32c294072cc6ec51f1692b803cb506fcfedca9d40eaec9",
    "zh:a53186599c57058be1509f904da512342cfdc5d808efdaf02dec15f0f3cb039a",
    "zh:c2e07b49b6efa676bdc7b00c06333ea1792a983a5720f9e2233db27323d2707c",
    "zh:cdc8fe1096103cf5374751e2e8408ec4abd2eb67d5a1c5151fe2c7ecfd525bef",
    "zh:dbdef21df0c012b0d08776f3d4f34eb0f2f229adfde07ff252a119e52c0f65b7",
  ]
}

All hashes, two platforms

# This file is maintained automatically by "terraform init".
# Manual edits may be lost in future updates.
provider "registry.terraform.io/hashicorp/null" {
  version = "3.0.0"
  hashes = [
    "h1:V1tzrSG6t3e7zWvUwRbGbhsWU2Jd/anrJpOl9XM+R/8=",
    "h1:ysHGBhBNkIiJLEpthB/IVCLpA1Qoncp3KbCTFGFZTO0=",
    "zh:05fb7eab469324c97e9b73a61d2ece6f91de4e9b493e573bfeda0f2077bc3a4c",
    "zh:1688aa91885a395c4ae67636d411475d0b831e422e005dcf02eedacaafac3bb4",
    "zh:24a0b1292e3a474f57c483a7a4512d797e041bc9c2fbaac42fe12e86a7fb5a3c",
    "zh:2fc951bd0d1b9b23427acc93be09b6909d72871e464088171da60fbee4fdde03",
    "zh:6db825759425599a326385a68acc6be2d9ba0d7d6ef587191d0cdc6daef9ac63",
    "zh:85985763d02618993c32c294072cc6ec51f1692b803cb506fcfedca9d40eaec9",
    "zh:a53186599c57058be1509f904da512342cfdc5d808efdaf02dec15f0f3cb039a",
    "zh:c2e07b49b6efa676bdc7b00c06333ea1792a983a5720f9e2233db27323d2707c",
    "zh:cdc8fe1096103cf5374751e2e8408ec4abd2eb67d5a1c5151fe2c7ecfd525bef",
    "zh:dbdef21df0c012b0d08776f3d4f34eb0f2f229adfde07ff252a119e52c0f65b7",
  ]
}

Only “h1:” hashes

# This file is maintained automatically by "terraform init".
# Manual edits may be lost in future updates.
provider "registry.terraform.io/hashicorp/null" {
  version = "3.0.0"
  hashes = [
    "h1:V1tzrSG6t3e7zWvUwRbGbhsWU2Jd/anrJpOl9XM+R/8=",
  ]
}

P.S. Interesting comment about why do you need lock file.

Related to 0.14 upgrade articles:

• Official documentation — Upgrading to Terraform v0.14
• Upgrading to Terraform 0.14 Experience -WARNING!
• Terraform Upgrade to v0.14 — Invalid Legacy Provider Address Error