IntenseWebs/opentofu
3
0
Fork 0
mirror of https://github.com/opentofu/opentofu.git synced 2025-02-25 18:45:20 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update website/docs/language/files (#226)

Browse Source 
Signed-off-by: Marcin Białoń <mbialon@spacelift.io>
This commit is contained in:
Marcin Białoń 2023-08-29 23:27:13 +02:00 committed by GitHub
parent 50084f6c0b
commit 9387ddb23f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 88 additions and 102 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

142
website/docs/language/files/dependency-lock.mdx
View File

@ -1,102 +1,96 @@
---
page_title: Dependency Lock File (.terraform.lock.hcl) - Configuration Language
description: >-
Terraform uses the dependency lock file .teraform.lock.hcl to track and select
OpenTF uses the dependency lock file .teraform.lock.hcl to track and select
provider versions. Learn about dependency installation and lock file changes.
---
# 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.
> **Hands-on:** Try the [Lock and Upgrade Provider Versions](/terraform/tutorials/configuration-language/provider-versioning?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
A Terraform configuration may refer to two different kinds of external
A OpenTF configuration may refer to two different kinds of external
dependency that come from outside of its own codebase:
- [Providers](/terraform/language/providers/requirements), which are plugins for Terraform
- [Providers](/opentf/language/providers/requirements), which are plugins for OpenTF
that extend it with support for interacting with various external systems.
- [Modules](/terraform/language/modules), which allow
splitting out groups of Terraform configuration constructs (written in the
Terraform language) into reusable abstractions.
- [Modules](/opentf/language/modules), which allow
splitting out groups of OpenTF configuration constructs (written in the
OpenTF 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
OpenTF itself and from the configurations that depend on them. For that
reason, OpenTF must determine which versions of those dependencies are
potentially compatible with the current configuration and which versions are
currently selected for use.
[Version constraints](/terraform/language/expressions/version-constraints) within the configuration
[Version constraints](/opentf/language/expressions/version-constraints) within the configuration
itself determine which versions of dependencies are _potentially_ compatible,
but after selecting a specific version of each dependency Terraform remembers
but after selecting a specific version of each dependency OpenTF 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
OpenTF does not remember version selections for remote modules, and so
OpenTF 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.
to ensure that OpenTF 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
OpenTF creates it and expects to find it in your current working directory
when you run OpenTF, 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
to signify that it is a lock file for various items that OpenTF 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](/terraform/cli/commands/init). You should
OpenTF automatically creates or updates the dependency lock file each time
you run [the `opentf init` command](/opentf/cli/commands/init). 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
The dependency lock file uses the same low-level syntax as the main OpenTF
language, but the dependency lock file is not itself a OpenTF 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
When `opentf init` is working on installing all of the providers needed for
a configuration, OpenTF 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
If a particular provider has no existing recorded selection, OpenTF 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
OpenTF 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
the `-upgrade` option when you run `opentf init`, in which case OpenTF
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
If a particular `opentf init` call makes changes to the lock file, OpenTF
will mention that as part of its output:
```
Terraform has made some changes to the provider dependency selections recorded
OpenTF 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),
[review the changes OpenTF 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
OpenTF 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:
@ -112,20 +106,20 @@ 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
regulations, and then trust that OpenTF will raise an error if a future
run of `opentf 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
that are signed with a cryptographic signature, OpenTF 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
In this case, the `opentf 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
@ -133,35 +127,35 @@ There are two special considerations with the "trust on first use" model:
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
installation method, such as a filesystem or network mirror, OpenTF 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
where you ran `opentf 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](/terraform/cli/commands/providers/lock),
which will then allow future calls to `terraform init` to verify that the
[the `opentf providers lock` command](/opentf/cli/commands/providers/lock),
which will then allow future calls to `opentf 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,
OpenTF 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
There are a few different types of changes that OpenTF can potentially make
to your lock file, which you may need to understand in order to review the
proposed changes. The following sections will describe these common situations.
### Dependency on a new provider
If you add a new entry to the
[provider requirements](/terraform/language/providers/requirements) for any module in your
[provider requirements](/opentf/language/providers/requirements) 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
dependency itself, `opentf 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.
@ -200,10 +194,10 @@ block in the dependency lock file.
The new lock file entry records several pieces of information:
- `version`: the exact version that Terraform selected based on the version
- `version`: the exact version that OpenTF 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
- `constraints`: all of the version constraints that OpenTF considered when
making this selection. (OpenTF 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
@ -213,8 +207,8 @@ The new lock file entry records several pieces of information:
### 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
If you run `opentf init -upgrade` to ask OpenTF to consider newer provider
versions that still match the configured version constraints, OpenTF may
then select a newer version for a provider and update its existing `provider`
block to reflect that change.
@ -262,7 +256,7 @@ block to reflect that change.
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
a change to the configured version constraints, OpenTF will also record
that change in the `constraints` value.
Because each version has its own set of distribution packages, switching to
@ -288,7 +282,7 @@ in the `provider` block has changed:
"zh:4c5682ba1e0fc7e2e602d3f103af1638f868c31fe80cc1a884a97f6dad6e1c11",
```
The addition of a new checksum into the `hashes` value represents Terraform
The addition of a new checksum into the `hashes` value represents OpenTF
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.
@ -299,14 +293,14 @@ 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
part of the OpenTF 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](/terraform/cli/config/config-file#provider-installation),
[provider installation methods](/opentf/cli/config/config-file#provider-installation),
such as filesystem mirrors using the unpacked directory layout.
- `h1:`: a mnemonic for "hash scheme 1", which is the current preferred hashing
@ -319,38 +313,38 @@ The two hashing schemes currently supported are:
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
Due to the limited scope of the `zh:` scheme, OpenTF 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
OpenTF 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
the above example, OpenTF 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
After confirming the `zh:` checksum match, OpenTF 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`
existing `provider` block for it), OpenTF 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
will consist primarily of hashes using that scheme, which OpenTF 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
can ask OpenTF to pre-populate hashes for a chosen set of platforms
using
[the `terraform providers lock` command](/terraform/cli/commands/providers/lock):
[the `opentf providers lock` command](/opentf/cli/commands/providers/lock):
```
terraform providers lock \
opentf providers lock \
-platform=linux_arm64 \
-platform=linux_amd64 \
-platform=darwin_amd64 \
@ -360,16 +354,16 @@ terraform providers lock \
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
the case where OpenTF will learn about a `h1:` equivalent only at a later
time. See the `opentf providers lock` documentation for more information on
this command.
### Providers that are no longer required
To determine whether there still exists a dependency on a given provider,
Terraform uses two sources of truth: the configuration itself, and the state.
OpenTF uses two sources of truth: the configuration itself, and the state.
If you remove the last dependency on a particular provider from both your
configuration and state, then `terraform init` will remove any existing lock
configuration and state, then `opentf init` will remove any existing lock
file entry for that provider.
```diff
@ -405,15 +399,7 @@ file entry for that provider.
```
If you add a new requirement for the same provider at a later date and run
`terraform init` again, Terraform will treat it as if it were
`opentf init` again, OpenTF will treat it as if it were
[an entirely new provider](#dependency-on-a-new-provider)
and so will not necessarily select the same version that was previously
selected and will not be able to verify that the checksums remained unchanged.
-> **Note:** In Terraform v1.0 and earlier, `terraform init` does not
automatically remove now-unneeded providers from the lock file, and instead
just ignores them. If you removed a provider dependency while using an
earlier version of Terraform and then upgraded to Terraform v1.1 or later
then you may see the error "missing or corrupted provider plugins", referring to
the stale lock file entries. If so, run `terraform init` with the new Terraform
version to tidy those unneeded entries and then retry the previous operation.

26
website/docs/language/files/index.mdx
View File

@ -1,20 +1,20 @@
---
page_title: Files and Directories - Configuration Language
description: >-
Learn how to name, organize, and store Terraform configuration files. Also
learn how Terraform evaluates modules.
Learn how to name, organize, and store OpenTF configuration files. Also
learn how OpenTF evaluates modules.
---
# Files and Directories
## File Extension
Code in the Terraform language is stored in plain text files with the `.tf` file
Code in the OpenTF language is stored in plain text files with the `.tf` file
extension. There is also
[a JSON-based variant of the language](/terraform/language/syntax/json) that is named with
[a JSON-based variant of the language](/opentf/language/syntax/json) that is named with
the `.tf.json` file extension.
Files containing Terraform code are often called _configuration files._
Files containing OpenTF code are often called _configuration files._
## Text Encoding
@ -27,32 +27,32 @@ line endings (CRLF), though both are accepted.
A _module_ is a collection of `.tf` and/or `.tf.json` files kept together in a
directory.
A Terraform module only consists of the top-level configuration files in a
A OpenTF module only consists of the top-level configuration files in a
directory; nested directories are treated as completely separate modules, and
are not automatically included in the configuration.
Terraform evaluates all of the configuration files in a module, effectively
OpenTF evaluates all of the configuration files in a module, effectively
treating the entire module as a single document. Separating various blocks into
different files is purely for the convenience of readers and maintainers, and
has no effect on the module's behavior.
A Terraform module can use [module calls](/terraform/language/modules) to
A OpenTF module can use [module calls](/opentf/language/modules) to
explicitly include other modules into the configuration. These child modules can
come from local directories (nested in the parent module's directory, or
anywhere else on disk), or from external sources like the
[Terraform Registry](https://registry.terraform.io).
[Module Registry](https://registry.terraform.io).
## The Root Module
Terraform always runs in the context of a single _root module._ A complete
_Terraform configuration_ consists of a root module and the tree of child
OpenTF always runs in the context of a single _root module._ A complete
_OpenTF configuration_ consists of a root module and the tree of child
modules (which includes the modules called by the root module, any modules
called by those modules, etc.).
- In Terraform CLI, the root module is the working directory where Terraform is
- In OpenTF CLI, the root module is the working directory where OpenTF is
invoked. (You can use command line options to specify a root module outside
the working directory, but in practice this is rare.)
- In Terraform Cloud and Terraform Enterprise, the root module for a workspace
- In TACOS (TF Automation and Collaboration Software), the root module for a workspace
defaults to the top level of the configuration directory (supplied via version
control repository or direct upload), but the workspace settings can specify a
subdirectory to use instead.

22
website/docs/language/files/override.mdx
View File

@ -7,25 +7,25 @@ description: >-
# Override Files
Terraform normally loads all of the `.tf` and `.tf.json` files within a
OpenTF normally loads all of the `.tf` and `.tf.json` files within a
directory and expects each one to define a distinct set of configuration
objects. If two files attempt to define the same object, Terraform returns
objects. If two files attempt to define the same object, OpenTF returns
an error.
In some rare cases, it is convenient to be able to override specific portions
of an existing configuration object in a separate file. For example, a
human-edited configuration file in the Terraform language native syntax
human-edited configuration file in the OpenTF language native syntax
could be partially overridden using a programmatically-generated file
in JSON syntax.
For these rare situations, Terraform has special handling of any configuration
For these rare situations, OpenTF has special handling of any configuration
file whose name ends in `_override.tf` or `_override.tf.json`. This special
handling also applies to a file named literally `override.tf` or
`override.tf.json`.
Terraform initially skips these _override files_ when loading configuration,
OpenTF initially skips these _override files_ when loading configuration,
and then afterwards processes each one in turn (in lexicographical order). For
each top-level block defined in an override file, Terraform attempts to find
each top-level block defined in an override file, OpenTF attempts to find
an already-defined object corresponding to that block and then merges the
override block contents into the existing object.
@ -38,7 +38,7 @@ override files apply changes to each block.
## Example
If you have a Terraform configuration `example.tf` with the following contents:
If you have a OpenTF configuration `example.tf` with the following contents:
```hcl
resource "aws_instance" "web" {
@ -55,7 +55,7 @@ resource "aws_instance" "web" {
}
```
Terraform will merge the latter into the former, behaving as if the original
OpenTF will merge the latter into the former, behaving as if the original
configuration had been as follows:
```hcl
@ -119,7 +119,7 @@ described above, but some special considerations apply due to the interactions
between the `type` and `default` arguments.
If the original block defines a `default` value and an override block changes
the variable's `type`, Terraform attempts to convert the default value to
the variable's `type`, OpenTF attempts to convert the default value to
the overridden type, producing an error if this conversion is not possible.
Conversely, if the original block defines a `type` and an override block changes
@ -154,7 +154,7 @@ original block. If both the base block and the override block both set
The presence of a block defining a backend (either `cloud` or `backend`) in an override
file always takes precedence over a block defining a backend in the original configuration.
That is, if a `cloud` block is set within the original configuration and a `backend` block is
set in the override file, Terraform will use the `backend` block specified in the override file upon merging.
set in the override file, OpenTF will use the `backend` block specified in the override file upon merging.
Similarly, if a `backend` block is set within the original configuration and a `cloud` block
is set in the override file, Terraform will use the `cloud` block specified in the override
is set in the override file, OpenTF will use the `cloud` block specified in the override
file upon merging.