github.com/hugorut/terraform@v1.1.3/website/docs/cli/commands/providers/lock.mdx (about)

     1  ---
     2  page_title: 'Command: providers lock'
     3  description: |-
     4    The `terraform providers lock` command adds new provider selection information
     5    to the dependency lock file without initializing the referenced providers.
     6  ---
     7  
     8  # Command: terraform providers lock
     9  
    10  The `terraform providers lock` consults upstream registries (by default) in
    11  order to write provider dependency information into
    12  [the dependency lock file](/language/files/dependency-lock).
    13  
    14  The common way to update the dependency lock file is as a side-effect of normal
    15  provider installation during
    16  [`terraform init`](/cli/commands/init), but there are several situations where that
    17  automatic approach may not be sufficient:
    18  
    19  * If you are running Terraform in an environment that uses
    20    [alternative provider installation methods](/cli/config/config-file#provider-installation),
    21    such as filesystem or network mirrors, normal provider installation will not
    22    access the origin registry for a provider and therefore Terraform will not
    23    be able to populate all of the possible package checksums for the selected
    24    provider versions.
    25  
    26    If you use `terraform lock` to write the official release checksums for a
    27    provider into the dependency lock file then future `terraform init` runs
    28    will verify the packages available in your selected mirror against the
    29    official checksums previously recorded, giving additional certainty that
    30    the mirror is serving the provider packages it is claiming to.
    31  
    32  * If your team runs Terraform across a number of different platforms (e.g.
    33    on both Windows and Linux) and the upstream registry for a provider is unable
    34    to provide signed checksums using the latest hashing scheme, subsequent runs
    35    of Terraform on other platforms may
    36    [add additional checksums to the lock file](/language/files/dependency-lock#new-provider-package-checksums).
    37    You can avoid that by pre-populating hashes for all of the platforms you
    38    intend to use, using the `terraform providers lock` command.
    39  
    40  -> `terraform providers lock` is available only in Terraform v0.14 or later.
    41  
    42  ## Usage
    43  
    44  Usage: `terraform providers lock [options] [providers...]`
    45  
    46  With no additional command line arguments, `terraform providers lock` will
    47  analyze the configuration in the current working directory to find all of
    48  the providers it depends on, and it will fetch the necessary data about those
    49  providers from their origin registries and then update
    50  [the dependency lock file](/language/files/dependency-lock) to
    51  include a selected version for each provider and all of the package checksums
    52  that are covered by the provider developer's cryptographic signature.
    53  
    54  ~> **Warning:** The `terraform providers lock` command prints information
    55  about what it has fetched and whether each package was signed using a
    56  cryptographic signature, but it cannot automatically verify that the
    57  providers are trustworthy and that they comply with your local system
    58  policies or relevant regulations. Review the signing key information
    59  in the output to confirm that you trust all of the signers before committing
    60  the updated lock file to your version control system.
    61  
    62  If you list one or more provider source addresses on the command line then
    63  `terraform providers lock` will restrict its work only to those providers,
    64  leaving the lock entries for other providers (if any) unchanged.
    65  
    66  You can customize the default behavior using the following additional option:
    67  
    68  * `-fs-mirror=PATH` - Direct Terraform to look for provider packages in the
    69    given local filesystem mirror directory, instead of in upstream registries.
    70    The given directory must use the usual filesystem mirror directory layout.
    71  
    72  * `-net-mirror=URL` - Direct Terraform to look for provider packages in the
    73    given network mirror service, instead of in upstream registries. The
    74    given URL must implement
    75    [the Terraform provider network mirror protocol](/internals/provider-network-mirror-protocol).
    76  
    77  * `-platform=OS_ARCH` - Specify a platform you intend to use to work with this
    78    Terraform configuration. Terraform will ensure that the providers are all
    79    available for the given platform and will save enough package checksums in
    80    the lock file to support _at least_ the specified platforms.
    81  
    82    Use this option multiple times to include checksums for multiple target
    83    systems.
    84  
    85    Target platform names consist of an operating system and a CPU
    86    architecture. For example, `linux_amd64` selects the Linux operating system
    87    running on an AMD64 or x86_64 CPU.
    88  
    89    There is more detail on this option in the following section.
    90  
    91  ## Specifying Target Platforms
    92  
    93  In your environment you may, for example, have both developers who work with
    94  your Terraform configuration on their Windows or macOS workstations _and_
    95  automated systems that apply the configuration while running on Linux.
    96  
    97  In that situation, you could choose to verify that all of your providers support
    98  all of those platforms, and to pre-populate the lock file with the necessary
    99  checksums, by running `terraform providers lock` and specifying those three
   100  platforms:
   101  
   102  ```
   103  terraform providers lock \
   104    -platform=windows_amd64 \ # 64-bit Windows
   105    -platform=darwin_amd64 \  # 64-bit macOS
   106    -platform=linux_amd64     # 64-bit Linux
   107  ```
   108  
   109  (The above example uses Unix-style shell wrapping syntax for readability. If
   110  you are running the command on Windows then you will need to put all of the
   111  arguments on a single line, and remove the backslashes and comments.)
   112  
   113  ## Lock Entries for In-house Providers
   114  
   115  An _in-house provider_ is one that isn't published on a real Terraform provider
   116  registry because it's developed and used only within a particular organization and
   117  distributed via either a filesystem mirror or network mirror.
   118  
   119  By default, `terraform providers lock` assumes all providers are available
   120  at a Terraform provider registry and tries to contact the origin registries
   121  in order to get access to the most detailed information about the provider
   122  packages.
   123  
   124  To create a lock entry for a particular provider that is available only in a
   125  local mirror, you can use either the `-fs-mirror` or `-net-mirror` command
   126  line options to override the default behavior of consulting the provider's
   127  origin registry:
   128  
   129  ```
   130  terraform providers lock \
   131    -fs-mirror=/usr/local/terraform/providers
   132    -platform=windows_amd64 \
   133    -platform=darwin_amd64 \
   134    -platform=linux_amd64 \
   135    tf.example.com/ourcompany/ourplatform
   136  ```
   137  
   138  (The above example uses Unix-style shell wrapping syntax for readability. If
   139  you are running the command on Windows then you will need to put all of the
   140  arguments on a single line, and remove the backslashes.)
   141  
   142  Because the command above includes the provider source address
   143  `tf.example.com/ourcompany/ourplatform`, `terraform providers lock` will only
   144  attempt to access that particular provider and will leave the lock entries
   145  for any other providers unchanged. If you have a variety of different providers
   146  available from different sources, you can run `terraform providers lock`
   147  multiple times and specify a different subset of your providers each time.
   148  
   149  The `-fs-mirror` and `-net-mirror` options have the same meaning as
   150  `filesystem_mirror` and `network_mirror` blocks in
   151  [the provider installation methods configuration](/cli/config/config-file#provider-installation),
   152  but specify only a single method in order to be explicit about where you
   153  intend to derive the package checksum information from.
   154  
   155  Note that only an origin registry can provide official checksums covered by
   156  the original developer's cryptographic signature. Lock entries created from
   157  filesystem or network mirrors will therefore cover only the exact platforms
   158  you requested, and the recorded checksums will be those reported by the
   159  mirror, rather than the origin registry's official checksums. If you want
   160  to ensure that the recorded checksums are the ones signed by the original
   161  provider publisher, run this command _without_ either the `-fs-mirror` or
   162  `-net-mirror` options to fetch all information from origin registries.
   163  
   164  If you wish, you can publish your in-house providers via an in-house provider
   165  registry, which will then allow locking and installation of those providers
   166  without any special options or additional CLI configuration. For more
   167  information, see
   168  [the provider registry protocol](/internals/provider-registry-protocol).