Terraform's December alpha changes provider cache eligibility
The December 7 Terraform 1.4 alpha previews a cache policy that requires matching lock-file checksums before reusing a global provider package.
A warm provider cache can change the lock file Terraform creates. The Terraform 1.4.0-alpha20221207 release, published on December 7, previews a different policy. A package in the optional global cache is eligible for reuse only when the current configuration's lock file already contains a matching checksum. First installation through a configuration can consequently fetch the package again even when another configuration has cached it.
This is an alpha release, and its release notes label the upcoming version unreleased. The behavior described here belongs to that preview. It gives users a specific compatibility change to examine before a stable release exists, without establishing what a later release will contain.
I consider the tradeoff useful because Terraform's reusable configuration needs a portable account of its provider dependencies. A local optimization that changes the completeness of that account can cause a problem elsewhere. The new policy makes the lock information the prerequisite for cache reuse.
Why the old cache interferes with locking
Pull request 32129 explains the history. Terraform's optional shared cache predates trust-on-first-use checksum locking. Reusing a cached package avoids downloading from upstream, but it also skips the opportunity to acquire the publisher's signed checksum set during that installation.
The mismatch involves package representation. The origin registry's legacy archive hashes describe zipped distribution packages. A global cache uses unpacked packages, so Terraform cannot verify an unpacked entry directly against an archive hash. Under the earlier compromise, Terraform preserved cache reuse and calculated more limited lock information locally.
That choice could produce a lock file that worked only for the current platform. Another platform needs a different provider package, even when the version is identical. The patch author describes this as an undesirable dependence of lock-file behavior on whether a package happened to be cached already.
The lock-file documentation from the July release supplies the relevant distinction. Archive hashes and content hashes have different inputs. Content hashes can verify an unpacked package, while an archive hash covers the original zip. A signed checksum set can also cover multiple platform packages that one locally calculated checksum does not describe.
The alpha reverses the priority
The preview first checks whether the existing lock information matches the cached package. A matching entry permits reuse. With no suitable lock information, Terraform proceeds through the configured installation source, normally the origin registry, so it can collect the available verification data.
Subsequent installation of the same locked package can then use the cache. This preserves the cache's role after the configuration has established its dependency information. The package does not become eligible simply because another configuration downloaded the same provider version earlier.
The patch also accounts for a cache entry that fails to match existing lock hashes. It treats the entry as unsuitable and attempts the configured installation source. That does not promise success. The source may also fail verification, but Terraform has an opportunity to obtain the package that the recorded information actually describes.
This matters for users with many separate configurations. The patch explicitly says they can need a download for each configuration's first encounter with a provider package. That is an intentional cost of gathering lock information, not evidence that the cache is disabled altogether.
A cache still has a narrower purpose than a mirror
The CLI configuration documentation at the alpha tag describes the optional cache as a way to share downloaded provider binaries among working directories. Each working directory normally receives its own installed provider copy. Caching can avoid repeated transfers, and Terraform can use symbolic links when possible.
A persistent cache setting belongs in the CLI configuration. The documented directory must already exist.
plugin_cache_dir = "$HOME/.terraform.d/plugin-cache"
The same reference distinguishes this directory from a filesystem mirror and prohibits using one directory for both roles. A mirror is an installation method, while the cache stores packages obtained through installation. The alpha's eligibility change depends on that distinction because bypassing a cache entry still leaves a configured source to consult.
The documentation also says Terraform does not automatically delete old cached provider versions. Cache reuse therefore does not imply lifecycle management for the cache contents. The December change concerns whether an existing entry can satisfy an installation, not how unused versions are removed.
I prefer describing this alpha through those exact boundaries. A cached binary can save a download once verification information exists, but its mere presence does not supply that information for a new configuration. The preview accepts a lower first-use cache hit rate so that initialization can obtain a more complete lock file through its configured installation source.