website: Initial docs for the new dependency lock file behaviors
This includes both the main documentation about the lock file itself and changes to related documentation about Terraform commands that interact with the lock file. We will likely continue to update this first pass of documentation as we get feedback and questions during the prerelease period.
This commit is contained in:
Martin Atkins
parent
e270291f19
commit
897cb72b36
|
|
@ -113,42 +113,48 @@ initialized with its child modules.
|
|||
|
||||
## Plugin Installation
|
||||
|
||||
Most Terraform providers are published separately from Terraform as plugins.
|
||||
During init, Terraform searches the configuration for both direct and indirect
|
||||
references to providers and attempts to load the required plugins.
|
||||
references to providers and attempts to install the plugins for those providers.
|
||||
|
||||
For [providers distributed by HashiCorp](/docs/providers/index.html),
|
||||
init will automatically download and install plugins if necessary. Plugins
|
||||
can also be manually installed in the user plugins directory, located at
|
||||
`~/.terraform.d/plugins` on most operating systems and
|
||||
`%APPDATA%\terraform.d\plugins` on Windows.
|
||||
For providers that are published in either
|
||||
[the public Terraform Registry](https://registry.terraform.io/) or in a
|
||||
third-party provider registry, `terraform init` will automatically find,
|
||||
download, and install the necessary provider plugins. If you cannot or do not
|
||||
wish to install providers from their origin registries, you can customize how
|
||||
Terraform installs providers using
|
||||
[the provider installation settings in the CLI configuration](./cli-config.html#provider-installation).
|
||||
|
||||
For more information about configuring and installing providers, see
|
||||
[Configuration: Providers](/docs/configuration/providers.html).
|
||||
For more information about specifying which providers are required for each
|
||||
of your modules, see [Provider Requirements](/docs/configuration/provider-requirements.html).
|
||||
|
||||
On subsequent runs, init only installs providers without acceptable versions
|
||||
installed. (This includes newly added providers, and providers whose installed
|
||||
versions can't meet the current version constraints.) Use `-upgrade` if you want
|
||||
to update _all_ providers to the newest acceptable version.
|
||||
After successful installation, Terraform writes information about the selected
|
||||
providers to [the dependency lock file](/docs/configuration/dependency-lock.html).
|
||||
You should commit this file to your version control system to ensure that
|
||||
when you run `terraform init` again in future Terraform will select exactly
|
||||
the same provider versions. Use the `-upgrade` option if you want Terraform
|
||||
to ignore the dependency lock file and consider installing newer versions.
|
||||
|
||||
You can modify `terraform init`'s plugin behavior with the following options:
|
||||
|
||||
- `-upgrade` — Update all previously installed plugins to the newest version
|
||||
that complies with the configuration's version constraints. This option does
|
||||
not apply to manually installed plugins.
|
||||
- `-get-plugins=false` — Skips plugin installation. Terraform will use plugins
|
||||
installed in the user plugins directory, and any plugins already installed
|
||||
for the current working directory. If the installed plugins aren't sufficient
|
||||
for the configuration, init fails.
|
||||
- `-plugin-dir=PATH` — Skips plugin installation and loads plugins _only_ from
|
||||
the specified directory. This ignores the user plugins directory and any
|
||||
plugins already installed in the current working directory. To restore the
|
||||
default behavior after using this option, run init again and pass an empty
|
||||
string to `-plugin-dir`.
|
||||
- `-verify-plugins=false` — Skips release signature validation when
|
||||
installing downloaded plugins (not recommended). Official plugin releases are
|
||||
digitally signed by HashiCorp, and Terraform verifies these signatures when
|
||||
automatically downloading plugins. This option disables that verification.
|
||||
(Terraform does not check signatures for manually installed plugins.)
|
||||
- `-upgrade` Upgrade all previously-selected plugins to the newest version
|
||||
that complies with the configuration's version constraints. This will
|
||||
cause Terraform to ignore any selections recorded in the dependency lock
|
||||
file, and to take the newest available version matching the configured
|
||||
version constraints.
|
||||
- `-get-plugins=false` — Skip plugin installation. If you previously ran
|
||||
`terraform init` without this option, the previously-installed plugins will
|
||||
remain available in your current working directory. If you have not
|
||||
previously run without this option, subsequent Terraform commands will
|
||||
fail due to the needed provider plugins being unavailable.
|
||||
- `-plugin-dir=PATH` — Force plugin installation to read plugins _only_ from
|
||||
the specified directory, as if it had been configured as a `filesystem_mirror`
|
||||
in the CLI configuration. If you intend to routinely use a particular
|
||||
filesystem mirror then we recommend
|
||||
[configuring Terraform's installation methods globally](./cli-config.html#provider-installation).
|
||||
You can use `-plugin-dir` as a one-time override for exceptional situations,
|
||||
such as if you are testing a local build of a provider plugin you are
|
||||
currently developing.
|
||||
|
||||
## Running `terraform init` in automation
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,170 @@
|
|||
---
|
||||
layout: "commands-providers"
|
||||
page_title: "Command: providers lock"
|
||||
sidebar_current: "docs-commands-providers-lock"
|
||||
description: |-
|
||||
The `terraform providers lock` command adds new provider selection information
|
||||
to the dependency lock file without initializing the referenced providers.
|
||||
---
|
||||
|
||||
# Command: terraform providers mirror
|
||||
|
||||
The `terraform providers lock` consults upstream registries (by default) in
|
||||
order to write provider dependency information into
|
||||
[the dependency lock file](/docs/configuration/dependency-lock.html).
|
||||
|
||||
The common way to update the dependency lock file is as a side-effect of normal
|
||||
provider installation during
|
||||
[`terraform init`](../init.html), but there are several situations where that
|
||||
automatic approach may not be sufficient:
|
||||
|
||||
* If you are running Terraform in an environment that uses
|
||||
[alternative provider installation methods](../cli-config.html#provider-installation),
|
||||
such as filesystem or network mirrors, normal provider installation will not
|
||||
access the origin registry for a provider and therefore Terraform will not
|
||||
be able to populate all of the possible package checksums for the selected
|
||||
provider versions.
|
||||
|
||||
If you use `terraform lock` to write the official release checksums for a
|
||||
provider into the dependency lock file then future `terraform init` runs
|
||||
will verify the packages available in your selected mirror against the
|
||||
official checksums previously recorded, giving additional certainty that
|
||||
the mirror is serving the provider packages it is claiming to.
|
||||
|
||||
* If your team runs Terraform across a number of different platforms (e.g.
|
||||
on both Windows and Linux) and the upstream registry for a provider is unable
|
||||
to provide signed checksums using the latest hashing scheme, subsequent runs
|
||||
of Terraform on other platforms may
|
||||
[add additional checksums to the lock file](/docs/configuration/dependency-lock.html#new-provider-package-checksums).
|
||||
You can avoid that by pre-populating hashes for all of the platforms you
|
||||
intend to use, using the `terraform providers lock` command.
|
||||
|
||||
-> `terraform providers lock` is available only in Terraform v0.14 or later.
|
||||
|
||||
## Usage
|
||||
|
||||
Usage: `terraform providers lock [options] [providers...]`
|
||||
|
||||
With no additional command line arguments, `terraform providers lock` will
|
||||
analyze the configuration in the current working directory to find all of
|
||||
the providers it depends on, and it will fetch the necessary data about those
|
||||
providers from their origin registries and then update
|
||||
[the dependency lock file](/docs/configuration/dependency-lock.html) to
|
||||
include a selected version for each provider and all of the package checksums
|
||||
that are covered by the provider developer's cryptographic signature.
|
||||
|
||||
~> **Warning:** The `terraform providers lock` command prints information
|
||||
about what it has fetched and whether each package was signed using a
|
||||
cryptographic signature, but it cannot automatically verify that the
|
||||
providers are trustworthy and that they comply with your local system
|
||||
policies or relevant regulations. Review the signing key information
|
||||
in the output to confirm that you trust all of the signers before committing
|
||||
the updated lock file to your version control system.
|
||||
|
||||
If you list one or more provider source addresses on the command line then
|
||||
`terraform providers lock` will restrict its work only to those providers,
|
||||
leaving the lock entries for other providers (if any) unchanged.
|
||||
|
||||
You can customize the default behavior using the following additional option:
|
||||
|
||||
* `-fs-mirror=PATH` - Direct Terraform to look for provider packages in the
|
||||
given local filesystem mirror directory, instead of in upstream registries.
|
||||
The given directory must use the usual filesystem mirror directory layout.
|
||||
|
||||
* `-net-mirror=URL` - Direct Terraform to look for provider packages in the
|
||||
given network mirror service, instead of in upstream registries. The
|
||||
given URL must implement
|
||||
[the Terraform provider network mirror protocol](/docs/internals/provider-network-mirror-protocol.html).
|
||||
|
||||
* `-platform=OS_ARCH` - Specify a platform you intend to use to work with this
|
||||
Terraform configuration. Terraform will ensure that the providers are all
|
||||
available for the given platform and will save enough package checksums in
|
||||
the lock file to support _at least_ the specified platforms.
|
||||
|
||||
Use this option multiple times to include checksums for multiple target
|
||||
systems.
|
||||
|
||||
Target platform names consist of an operating system and a CPU
|
||||
architecture. For example, `linux_amd64` selects the Linux operating system
|
||||
running on an AMD64 or x86_64 CPU.
|
||||
|
||||
There is more detail on this option in the following section.
|
||||
|
||||
## 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 \ # 64-bit Windows
|
||||
-platform=darwin_amd64 \ # 64-bit macOS
|
||||
-platform=linux_amd64 # 64-bit Linux
|
||||
```
|
||||
|
||||
(The above example uses Unix-style shell wrapping syntax for readability. If
|
||||
you are running the command on Windows then you will need to put all of the
|
||||
arguments on a single line, and remove the backslashes and comments.)
|
||||
|
||||
## Lock Entries for In-house Providers
|
||||
|
||||
An _in-house provider_ is one that isn't published on a real Terraform provider
|
||||
registry because it's developed and used only within a particular organization and
|
||||
distributed via either a filesystem mirror or network mirror.
|
||||
|
||||
By default, `terraform providers lock` assumes all providers are available
|
||||
at a Terraform provider registry and tries to contact the origin registries
|
||||
in order to get access to the most detailed information about the provider
|
||||
packages.
|
||||
|
||||
To create a lock entry for a particular provider that is available only in a
|
||||
local mirror, you can use either the `-fs-mirror` or `-net-mirror` command
|
||||
line options to override the default behavior of consulting the provider's
|
||||
origin registry:
|
||||
|
||||
```
|
||||
terraform providers lock \
|
||||
-fs-mirror=/usr/local/terraform/providers
|
||||
-platform=windows_amd64 \
|
||||
-platform=darwin_amd64 \
|
||||
-platform=linux_amd64 \
|
||||
tf.example.com/ourcompany/ourplatform
|
||||
```
|
||||
|
||||
(The above example uses Unix-style shell wrapping syntax for readability. If
|
||||
you are running the command on Windows then you will need to put all of the
|
||||
arguments on a single line, and remove the backslashes.)
|
||||
|
||||
Because the command above includes the provider source address
|
||||
`tf.example.com/ourcompany/ourplatform`, `terraform providers lock` will only
|
||||
attempt to access that particular provider and will leave the lock entries
|
||||
for any other providers unchanged. If you have a variety of different providers
|
||||
available from different sources, you can run `terraform providers lock`
|
||||
multiple times and specify a different subset of your providers each time.
|
||||
|
||||
The `-fs-mirror` and `-net-mirror` options have the same meaning as
|
||||
`filesystem_mirror` and `network_mirror` blocks in
|
||||
[the provider installation methods configuration](../cli-config.html#provider-installation),
|
||||
but specify only a single method in order to be explicit about where you
|
||||
intend to derive the package checksum information from.
|
||||
|
||||
Note that only an origin registry can provide official checksums covered by
|
||||
the original developer's cryptographic signature. Lock entries created from
|
||||
filesystem or network mirrors will therefore cover only the exact platforms
|
||||
you requested, and the recorded checksums will be those reported by the
|
||||
mirror, rather than the origin registry's official checksums. If you want
|
||||
to ensure that the recorded checksums are the ones signed by the original
|
||||
provider publisher, run this command _without_ either the `-fs-mirror` or
|
||||
`-net-mirror` options to fetch all information from origin registries.
|
||||
|
||||
If you wish, you can publish your in-house providers via an in-house provider
|
||||
registry, which will then allow locking and installation of those providers
|
||||
without any special options or additional CLI configuration. For more
|
||||
information, see
|
||||
[the provider registry protocol](/docs/internals/provider-registry-protocol.html).
|
||||
|
|
@ -0,0 +1,361 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Dependency Lock File (.terraform.lock.hcl) - Configuration Language"
|
||||
---
|
||||
|
||||
# Dependency Lock File
|
||||
|
||||
-> **Note:** This page is about a feature of Terraform 0.14 and later. Prior
|
||||
versions of Terraform did not track dependency selections at all, so the
|
||||
information here is not relevant to those versions.
|
||||
|
||||
A Terraform configuration may refer to two different kinds of external
|
||||
dependency that come from outside of its own codebase:
|
||||
|
||||
* [Providers](./provider-requirements.html), which are plugins for Terraform
|
||||
that extend it with support for interacting with various external systems.
|
||||
* [Modules](./modules.html), which allow splitting out groups of Terraform
|
||||
configuration constructs (written in the Terraform language) into reusable
|
||||
abstractions.
|
||||
|
||||
Both of these dependency types can be published and updated independently from
|
||||
Terraform itself and from the configurations that depend on them. For that
|
||||
reason, Terraform must determine which versions of those dependencies are
|
||||
potentially compatible with the current configuration and which versions are
|
||||
currently selected for use.
|
||||
|
||||
[Version constraints](./version-constraints.html) within the configuration
|
||||
itself determine which versions of dependencies are _potentially_ compatible,
|
||||
but after selecting a specific version of each dependency Terraform remembers
|
||||
the decisions it made in a _dependency lock file_ so that it can (by default)
|
||||
make the same decisions again in future.
|
||||
|
||||
At present, the dependency lock file tracks only _provider_ dependencies.
|
||||
Terraform does not remember version selections for remote modules, and so
|
||||
Terraform will always select the newest available module version that meets
|
||||
the specified version constraints. You can use an _exact_ version constraint
|
||||
to ensure that Terraform will always select the same module version.
|
||||
|
||||
## Lock File Location
|
||||
|
||||
The dependency lock file is a file that belongs to the configuration as a
|
||||
whole, rather than to each separate module in the configuration. For that reason
|
||||
Terraform creates it and expects to find it in your current working directory
|
||||
when you run Terraform, which is also the directory containing the `.tf` files
|
||||
for the root module of your configuration.
|
||||
|
||||
The lock file is always named `.terraform.lock.hcl`, and this name is intended
|
||||
to signify that it is a lock file for various items that Terraform caches in
|
||||
the `.terraform` subdirectory of your working directory.
|
||||
|
||||
Terraform automatically creates or updates the dependency lock file each time
|
||||
you run [the `terraform init` command](/docs/commands/init.html). 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 dependency lock file uses the same low-level syntax as the main Terraform
|
||||
language, but the dependency lock file is not itself a Terraform language
|
||||
configuration file. It is named with the suffix `.hcl` instead of `.tf` in
|
||||
order to signify that difference.
|
||||
|
||||
## 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.
|
||||
|
||||
If a particular `terraform init` call makes changes to the lock file, Terraform
|
||||
will mention that as part of its output:
|
||||
|
||||
```
|
||||
Terraform has made some changes to the provider dependency selections recorded
|
||||
in the .terraform.lock.hcl file. Review those changes and commit them to your
|
||||
version control system if they represent changes you intended to make.
|
||||
```
|
||||
|
||||
When you see this message, you can use your version control system to
|
||||
[review the changes Terraform has proposed in the file](#understanding-lock-file-changes),
|
||||
and if they represent changes you made intentionally you can send the change
|
||||
through your team's usual code review process.
|
||||
|
||||
### Checksum verification
|
||||
|
||||
Terraform will also verify that each package it installs matches at least one
|
||||
of the checksums it previously recorded in the lock file, if any, returning an
|
||||
error if none of the checksums match:
|
||||
|
||||
```
|
||||
Error: Failed to install provider
|
||||
|
||||
Error while installing hashicorp/azurerm v2.1.0: the current package for
|
||||
registry.terraform.io/hashicorp/azurerm 2.1.0 doesn't match any of the
|
||||
checksums previously recorded in the dependency lock file.
|
||||
```
|
||||
|
||||
This checksum verification is intended to represent a
|
||||
_[trust on first use](https://en.wikipedia.org/wiki/Trust_on_first_use)_
|
||||
approach. When you add a new provider for the first time you can verify it
|
||||
in whatever way you choose or any way you are required to by relevant
|
||||
regulations, and then trust that Terraform will raise an error if a future
|
||||
run of `terraform init` encounters a non-matching package for the same
|
||||
provider version.
|
||||
|
||||
There are two special considerations with the "trust on first use" model:
|
||||
|
||||
* If you install a provider from an origin registry which provides checksums
|
||||
that are signed with a cryptographic signature, Terraform will treat all
|
||||
of the signed checksums as valid as long as one checksum matches. The lock
|
||||
file will therefore include checksums for both the package you installed for
|
||||
your current platform _and_ any other packages that might be available for
|
||||
other platforms.
|
||||
|
||||
In this case, the `terraform init` output will include the fingerprint of
|
||||
the key that signed the checksums, with a message like
|
||||
`(signed by a HashiCorp partner, key ID DC9FC6B1FCE47986)`. You may wish to
|
||||
confirm that you trust the holder of the given key before committing the
|
||||
lock file containing the signed checksums, or to retrieve and verify the
|
||||
full set of available packages for the given provider version.
|
||||
|
||||
* If you install a provider for the first time using an alternative
|
||||
installation method, such as a filesystem or network mirror, Terraform will
|
||||
not be able to verify the checksums for any platform other than the one
|
||||
where you ran `terraform init`, and so it will not record the checksums
|
||||
for other platforms and so the configuration will not be usable on any other
|
||||
platform.
|
||||
|
||||
To avoid this problem you can pre-populate checksums for a variety of
|
||||
different platforms in your lock file using
|
||||
[the `terraform providers lock` command](/docs/commands/providers/lock.html),
|
||||
which will then allow future calls to `terraform init` to verify that the
|
||||
packages available in your chosen mirror match the official packages from
|
||||
the provider's origin registry.
|
||||
|
||||
## Understanding Lock File Changes
|
||||
|
||||
Because the dependency lock file is primarily maintained automatically by
|
||||
Terraform itself, rather than being updated manually by you or your team,
|
||||
your version control system may show you that the file has changed.
|
||||
|
||||
There are a few different types of changes that Terraform can potentially make
|
||||
to your lock file, which you may need to understand in order to review the
|
||||
propsed changes. The following sections will describe these common situations.
|
||||
|
||||
### Dependency on a new provider
|
||||
|
||||
If you add a new entry to the
|
||||
[provider requirements](./provider-requirements.html) for any module in your
|
||||
configuration, or if you add an external module that includes a new provider
|
||||
dependency itself, `terraform init` will respond to that by selecting the
|
||||
newest version of that provider which meets all of the version constraints
|
||||
in the configuration, and it will record its decision as a new `provider`
|
||||
block in the dependency lock file.
|
||||
|
||||
```diff
|
||||
--- .terraform.lock.hcl 2020-10-07 16:12:07.539570634 -0700
|
||||
+++ .terraform.lock.hcl 2020-10-07 16:12:15.267487237 -0700
|
||||
@@ -6,6 +6,26 @@
|
||||
]
|
||||
}
|
||||
|
||||
+provider "registry.terraform.io/hashicorp/azurerm" {
|
||||
+ version = "2.30.0"
|
||||
+ constraints = "~> 2.12"
|
||||
+ hashes = [
|
||||
+ "h1:FJwsuowaG5CIdZ0WQyFZH9r6kIJeRKts9+GcRsTz1+Y=",
|
||||
+ "h1:c/ntSXrDYM1mUir2KufijYebPcwKqS9CRGd3duDSGfY=",
|
||||
+ "h1:yre4Ph76g9H84MbuhZ2z5MuldjSA4FsrX6538O7PCcY=",
|
||||
+ "zh:04f0a50bb2ba92f3bea6f0a9e549ace5a4c13ef0cbb6975494cac0ef7d4acb43",
|
||||
+ "zh:2082e12548ebcdd6fd73580e83f626ed4ed13f8cdfd51205d8696ffe54f30734",
|
||||
+ "zh:246bcc449e9a92679fb30f3c0a77f05513886565e2dcc66b16c4486f51533064",
|
||||
+ "zh:24de3930625ac9014594d79bfa42d600eca65e9022b9668b54bfd0d924e21d14",
|
||||
+ "zh:2a22893a576ff6f268d9bf81cf4a56406f7ba79f77826f6df51ee787f6d2840a",
|
||||
+ "zh:2b27485e19c2aaa9f15f29c4cff46154a9720647610171e30fc6c18ddc42ec28",
|
||||
+ "zh:435f24ce1fb2b63f7f02aa3c84ac29c5757cd29ec4d297ed0618423387fe7bd4",
|
||||
+ "zh:7d99725923de5240ff8b34b5510569aa4ebdc0bdb27b7bac2aa911a8037a3893",
|
||||
+ "zh:7e3b5d0af3b7411dd9dc65ec9ab6caee8c191aee0fa7f20fc4f51716e67f50c0",
|
||||
+ "zh:da0af4552bef5a29b88f6a0718253f3bf71ce471c959816eb7602b0dadb469ca",
|
||||
+ ]
|
||||
+}
|
||||
+
|
||||
provider "registry.terraform.io/newrelic/newrelic" {
|
||||
version = "2.1.2"
|
||||
constraints = "~> 2.1.1"
|
||||
```
|
||||
|
||||
The new lock file entry records several pieces of information:
|
||||
|
||||
* `version`: the exact version that Terraform selected based on the version
|
||||
constraints in the configuration.
|
||||
* `constraints`: all of the version constraints that Terraform considered when
|
||||
making this selection. (Terraform doesn't actually use this information to
|
||||
make installation decisions, but includes it to help explain to human readers
|
||||
how the previous decision was made.)
|
||||
* `hashes`: a number of checksums that are all considered to be valid for
|
||||
packages implementing the selected version of this provider on different
|
||||
platforms. The meaning of these hashes is explained more under
|
||||
_[New provider package checksums](#new-provider-package-checksums)_ below.
|
||||
|
||||
### New version of an existing provider
|
||||
|
||||
If you run `terraform init -upgrade` to ask Terraform to consider newer provider
|
||||
versions that still match the configured version constraints, Terraform may
|
||||
then select a newer version for a provider and update its existing `provider`
|
||||
block to reflect that change.
|
||||
|
||||
```diff
|
||||
--- .terraform.lock.hcl 2020-10-07 16:44:25.819579509 -0700
|
||||
+++ .terraform.lock.hcl 2020-10-07 16:43:42.785665945 -0700
|
||||
@@ -7,22 +7,22 @@
|
||||
}
|
||||
|
||||
provider "registry.terraform.io/hashicorp/azurerm" {
|
||||
- version = "2.1.0"
|
||||
- constraints = "~> 2.1.0"
|
||||
+ version = "2.0.0"
|
||||
+ constraints = "2.0.0"
|
||||
hashes = [
|
||||
- "h1:EOJImaEaVThWasdqnJjfYc6/P8N/MRAq1J7avx5ZbV4=",
|
||||
- "zh:0015b491cf9151235e57e35ea6b89381098e61bd923f56dffc86026d58748880",
|
||||
- "zh:4c5682ba1e0fc7e2e602d3f103af1638f868c31fe80cc1a884a97f6dad6e1c11",
|
||||
- "zh:57bac885b108c91ade4a41590062309c832c9ab6bf6a68046161636fcaef1499",
|
||||
- "zh:5810d48f574c0e363c969b3f45276369c8f0a35b34d6202fdfceb7b85b3ac597",
|
||||
- "zh:5c6e37a44462b8662cf9bdd29ce30523712a45c27c5d4711738705be0785db41",
|
||||
- "zh:64548940a3387aa3a752e709ee9eb9982fa820fe60eb60e5f212cc1d2c58549e",
|
||||
- "zh:7f46749163da17330bbb5293dc825333c86304baa0a7c6256650ac536b4567c8",
|
||||
- "zh:8f8970f2df75ac43ffdd112055ee069d8bd1030f7eb4367cc4cf494a1fa802c3",
|
||||
- "zh:9ad693d00dc5d7d455d06faba70e716bce727c6706f7293288e87fd7956b8fe0",
|
||||
- "zh:b6e3cb55e6aec62b47edd0d2bd5e14bd6a2bcfdac65930a6e9e819934734c57b",
|
||||
- "zh:d6a3f3b9b05c28ecf3919e9e7afa185805a6d7442fc4b3eedba749c2731d1f0e",
|
||||
- "zh:d81fb624a357c57c7ea457ce543d865b39b12f26c2edd58a2f7cd43326c91010",
|
||||
+ "h1:bigGXBoRbp7dv79bEEn+aaju8575qEXHQ57XHVPJeB8=",
|
||||
+ "zh:09c603c8904ca4a5bc19e82335afbc2837dcc4bee81e395f9daccef2f2cba1c8",
|
||||
+ "zh:194a919d4836d6c6d4ce598d0c66cce00ddc0d0b5c40d01bb32789964d818b42",
|
||||
+ "zh:1f269627df4e266c4e0ef9ee2486534caa3c8bea91a201feda4bca525005aa0a",
|
||||
+ "zh:2bae3071bd5f8e553355c4b3a547d6efe1774a828142b762e9a4e85f79be7f63",
|
||||
+ "zh:6c98dfa5c3468e8d02e2b3af7c4a8a14a5d469ce5a642909643b413a17ca338b",
|
||||
+ "zh:7af78f61666fd45fbf428161c061ea2623162d601b79dc71d6a5158756853ffa",
|
||||
+ "zh:883c2df86ae9ba2a5c167cf5c2c7deca0239171a224d6d335f0fd6dd9c283830",
|
||||
+ "zh:a2028379078577d8ff5ecfca6e8a8b25a25ffb1686de0ee52a7fe8011783488b",
|
||||
+ "zh:abe6ef399552fd3861a454a839cd978c1d15735658fdc00f9054435aff0f4620",
|
||||
+ "zh:c30b1bf14077913c3cdf34979b1434dbb1353cb5995eb3956b191c50538b64a9",
|
||||
+ "zh:ca64ae2ad9793e5631e3b0b9327f7cb22cb5d8e9de57be7d85821791b1d5a375",
|
||||
+ "zh:fffe56904a38109bb8d613b02808a177c3ddfac19f03b3aac799281fea38f475",
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
The primary effect of selecting a new provider version is to change the
|
||||
value of `version` in the `provider` block. If the upgrade came along with
|
||||
a change to the configured version constraints, Terraform will also record
|
||||
that change in the `constraints` value.
|
||||
|
||||
Because each version has its own set of distribution packages, switching to
|
||||
a new version will also tend to replace all of the values in `hashes`, to
|
||||
reflect the checksums of the packages for the new version.
|
||||
|
||||
### New provider package checksums
|
||||
|
||||
A more subtle change you may see in a `provider` block is the addition of
|
||||
new checksums that were not previously recorded, even though nothing else
|
||||
in the `provider` block has changed:
|
||||
|
||||
```diff
|
||||
--- .terraform.lock.hcl 2020-10-07 17:24:23.397892140 -0700
|
||||
+++ .terraform.lock.hcl 2020-10-07 17:24:57.423130253 -0700
|
||||
@@ -10,6 +10,7 @@
|
||||
version = "2.1.0"
|
||||
constraints = "~> 2.1.0"
|
||||
hashes = [
|
||||
+ "h1:1xvaS5D8B8t6J6XmXxX8spo97tAzjhacjedFX1B47Fk=",
|
||||
"h1:EOJImaEaVThWasdqnJjfYc6/P8N/MRAq1J7avx5ZbV4=",
|
||||
"zh:0015b491cf9151235e57e35ea6b89381098e61bd923f56dffc86026d58748880",
|
||||
"zh:4c5682ba1e0fc7e2e602d3f103af1638f868c31fe80cc1a884a97f6dad6e1c11",
|
||||
```
|
||||
|
||||
The addition of a new checksum into the `hashes` value represents Terraform
|
||||
gradually transitioning between different _hashing schemes_. The `h1:` and
|
||||
`zh:` prefixes on these values represent different hashing schemes, each
|
||||
of which represents calculating a checksum using a different algorithm.
|
||||
We may occasionally introduce new hashing schemes if we learn of limitations
|
||||
in the existing schemes or if a new scheme offers some considerable
|
||||
additional benefit.
|
||||
|
||||
The two hashing schemes currently supported are:
|
||||
|
||||
* `zh:`: a mnemonic for "zip hash", this is a legacy hash format which is
|
||||
part of the Terraform provider registry protocol and is therefore used for
|
||||
providers that you install directly from an origin registry.
|
||||
|
||||
This hashing scheme captures a SHA256 hash of each of the official `.zip`
|
||||
packages indexed in the origin registry. This is an effective scheme for
|
||||
verifying the official release packages when installed from a registry, but
|
||||
it's not suitable for verifying packages that come from other
|
||||
[provider installation methods](/docs/commands/cli-config.html#provider-installation),
|
||||
such as filesystem mirrors using the unpacked directory layout.
|
||||
|
||||
* `h1:`: a mnemonic for "hash scheme 1", which is the current preferred hashing
|
||||
scheme.
|
||||
|
||||
Hash scheme 1 is also a SHA256 hash, but is one computed from the _contents_
|
||||
of the provider distribution package, rather than of the `.zip` archive
|
||||
it's contained within. This scheme therefore has the advantage that it can
|
||||
be calculated for an official `.zip` file, an unpacked directory with the
|
||||
same contents, or a recompressed `.zip` file which contains the same files
|
||||
but potentially different metadata or compression schemes.
|
||||
|
||||
Due to the limited scope of the `zh:` scheme, Terraform will
|
||||
opportunistically add in the corresponding `h1:` checksums as it learns
|
||||
of them, which is what caused the addition of a second `h1:` checksum
|
||||
in the example change shown above.
|
||||
|
||||
Terraform will add a new hash to an existing provider only if the hash is
|
||||
calculated from a package that _also_ matches one of the existing hashes. In
|
||||
the above example, Terraform installed a `hashicorp/azurerm` package for a
|
||||
different platform than that which produced the original `h1:` checksum, but was
|
||||
able to match it against one of the `zh:` checksums recorded previously.
|
||||
After confirming the `zh:` checksum match, Terraform then recorded the
|
||||
corresponding `h1:` checksum in order to gradually migrate from the old scheme
|
||||
to the new scheme.
|
||||
|
||||
When installing a particular provider for the first time (where there is no
|
||||
existing `provider` block for it), Terraform will pre-populate the `hashes`
|
||||
value with any checksums that are covered by the provider developer's
|
||||
cryptographic signature, which usually covers all of the available packages
|
||||
for that provider version across all supported platforms. However, because
|
||||
the provider registry protocol still uses the `zh:` scheme, the initial set
|
||||
will consist primarily of hashes using that scheme, which Terraform will then
|
||||
upgrade opportunistically as you install the packages on different platforms.
|
||||
|
||||
If you wish to avoid ongoing additions of new `h1:` hashes as you work with
|
||||
your configuration on new target platforms, or if you are installing providers
|
||||
from a mirror that therefore can't provide official signed checksums, you
|
||||
can ask Terraform to pre-populate hashes for a chosen set of platforms
|
||||
using
|
||||
[the `terraform providers lock` command](/docs/commands/providers/lock.html):
|
||||
|
||||
```
|
||||
terraform providers lock \
|
||||
-platform=linux_arm64 \
|
||||
-platform=linux_amd64 \
|
||||
-platform=darwin_amd64 \
|
||||
-platform=windows_amd64
|
||||
```
|
||||
|
||||
The above command will download and verify the official packages for all of
|
||||
the required providers across all four of the given platforms, and then record
|
||||
both `zh:` and `h1:` checksums for each of them in the lock file, thus avoiding
|
||||
the case where Terraform will learn about a `h1:` equivalent only at a later
|
||||
time. See the `terraform providers lock` documentation for more information on
|
||||
this command.
|
||||
|
|
@ -49,13 +49,17 @@ Terraform finds and installs providers when
|
|||
automatically download providers from a Terraform registry, or load them from a
|
||||
local mirror or cache.
|
||||
|
||||
When a new provider is added to a configuration, Terraform must install the
|
||||
provider before it can be used. If you are using a persistent working directory,
|
||||
When you add a new provider to a configuration, Terraform must install the
|
||||
provider in order to use it. If you are using a persistent working directory,
|
||||
you can run `terraform init` again to install new providers.
|
||||
|
||||
Providers downloaded by `terraform init` are only installed for the current
|
||||
working directory; other working directories can have their own installed
|
||||
provider plugins, which might be different versions.
|
||||
provider plugins. To help ensure that each working directory will use the same
|
||||
selected versions, `terraform init` records its version selections in
|
||||
your configuration's [dependency lock file](dependency-lock.html), named
|
||||
`.terraform.lock.hcl` and will always make those same selections unless
|
||||
you run `terraform init -upgrade` to update them.
|
||||
|
||||
To save time and bandwidth, Terraform supports an optional plugin cache. You can
|
||||
enable the cache using the `plugin_cache_dir` setting in
|
||||
|
|
|
|||
|
|
@ -10,6 +10,9 @@
|
|||
<li<%= sidebar_current("docs-commands-providers") %>>
|
||||
<a href="/docs/commands/providers.html">providers</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-commands-providers-lock") %>>
|
||||
<a href="/docs/commands/providers/lock.html">lock</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-providers-mirror") %>>
|
||||
<a href="/docs/commands/providers/mirror.html">mirror</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue