Terraform 1.2.6 explains incomplete provider lock files

A provider lock file can work on the machine that created it and fail on another platform without any change in the selected provider version. Terraform 1.2.6, released on July 27, adds a warning and guidance when initialization cannot fully populate provider checksums. It also links relevant documentation when initialization fails because checksums are missing.

The failure is easier to understand once provider selection and package verification are separated. A provider version identifies a release, but that release can contain different packages for different operating systems and processor architectures. Recording a checksum for one package does not establish the checksum for every other package bearing the same version.

I consider reproducible provider installation part of Terraform's configuration model. The DSL delegates operations to provider plugins, so agreement about configuration is incomplete without agreement about the plugin packages executing it. This patch improves the explanation when a lock file records less information than a user might reasonably assume.

The version is only part of the lock

The dependency-lock reference shipped with 1.2.6 describes a provider entry containing the selected version, explanatory version constraints, and accepted package hashes. The hashes can cover packages for different platforms. They are not simply a checksum of the version string.

Two supported hash schemes explain some otherwise confusing lock-file changes. A zh: entry hashes a distribution zip archive. An h1: entry hashes its contents, which lets Terraform verify the same files after unpacking or recompression. Both use SHA256, but their inputs differ.

Terraform can add a content hash after installing a package that matches an already recorded archive hash. This is why a lock file can gain a hash while its provider version remains unchanged. The additional line can represent information about a newly used platform or a different supported hash scheme, rather than an upgrade.

The documentation describes initial installation as recording checksums covered by the publisher's cryptographic signature when those are available. That set usually covers the available packages across supported platforms. Installation through a mirror can provide less information because it does not necessarily retrieve the origin registry's signed checksum set.

Initialization can succeed with incomplete coverage

Pull request 31399 adds tracking around provider lock updates. The implementation receives information about locally calculated hashes, signed hashes, and previous hashes. That context lets initialization identify installations where the lock information remains local to the current platform.

The warning names affected providers and explains the platform limitation. It also gives a command for calculating checksums for another target. The important behavior is a warning about future portability even when installation on the current machine has succeeded.

This is distinct from rejecting a package that fails verification. A successful local installation and an incomplete cross-platform lock file can coexist. The diagnostic makes the incomplete information visible before another machine encounters it as a failed initialization.

That distinction is useful in a mixed workstation and automation environment. A developer might install a provider through a customized method on one system while an automated runner needs another package of the same release. A version match by itself cannot make the runner's package match the workstation package's content hash.

Locking platforms explicitly

The versioned providers-lock command reference documents an explicit way to populate the information. The command consults origin registries by default and updates dependency selections and checksums without initializing the providers for use. Repeated platform flags select the systems the configuration needs.

terraform providers lock -platform=linux_amd64 -platform=darwin_amd64

That command requests enough package information for both named platforms. The reference says it checks provider availability for each requested platform and records the corresponding checksums. It can therefore establish the necessary information before normal initialization happens on those systems.

The command also supports filesystem and network mirrors. Those options matter for providers distributed internally without an origin registry. A mirror-derived lock entry covers the requested platforms using checksums from the mirror. It does not acquire the original publisher's signed checksum set merely because the command is called lock.

The reference makes that trust distinction explicit. Official signed checksums come from the origin registry. For a provider available through such a registry, running without mirror overrides obtains that source's information. For an internal provider distributed only through a mirror, the mirror remains the source of the recorded package data.

I prefer this explanation to treating every checksum problem as a request to regenerate the lock file. There are separate questions about which version is selected, which platforms have recorded packages, and where the verification information originated. Terraform 1.2.6 gives users more of that context at initialization, while explicit platform locking records the package information the next machine will need.