github.com/muratcelep/terraform@v1.1.0-beta2-not-internal-4/website/docs/cli/commands/providers/lock.html.md (about)

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