mirror of
https://github.com/opentffoundation/opentf.git
synced 2025-12-23 03:34:30 -05:00
9198166771
Signed-off-by: Tom Spurling <tom@tspurling.co.uk> Co-authored-by: Tom Spurling <tom@tspurling.co.uk>
131 lines
4.9 KiB
Plaintext
131 lines
4.9 KiB
Plaintext
---
|
|
description: >-
|
|
The terraform block allows you to configure OpenTofu behavior, including the
|
|
OpenTofu version, backend, integration with TACOS (TF Automation and Collaboration Software),
|
|
and required providers.
|
|
---
|
|
|
|
# OpenTofu Settings
|
|
|
|
The special `terraform` configuration block type is used to configure some
|
|
behaviors of OpenTofu itself, such as requiring a minimum OpenTofu version to
|
|
apply your configuration.
|
|
|
|
:::note
|
|
As a part of [OpenTofu v1.x Compatibility Promises](../../language/v1-compatibility-promises.mdx),
|
|
the `terraform` block stays as-is. A `tofu` block may be introduced in the future, but it doesn't
|
|
exist yet.
|
|
:::
|
|
|
|
|
|
## OpenTofu `terraform` Block Syntax
|
|
|
|
OpenTofu settings are gathered together into `terraform` blocks:
|
|
|
|
```hcl
|
|
terraform {
|
|
# ...
|
|
}
|
|
```
|
|
|
|
Each `terraform` block can contain a number of settings related to OpenTofu's
|
|
behavior. Within a `terraform` block, only constant values can be used;
|
|
arguments may not refer to named objects such as resources, input variables,
|
|
etc, and may not use any of the OpenTofu language built-in functions.
|
|
|
|
The various options supported within a `terraform` block are described in the
|
|
following sections.
|
|
|
|
## Configuring an OpenTofu Backend
|
|
|
|
The nested `backend` block configures which state backend OpenTofu should use.
|
|
|
|
The syntax and behavior of the `backend` block is described in
|
|
[Backend Configuration](../../language/settings/backends/configuration.mdx).
|
|
|
|
## Specifying a Required OpenTofu Version
|
|
|
|
The `required_version` setting accepts a [version constraint string](../../language/expressions/version-constraints.mdx), which specifies which versions of OpenTofu
|
|
can be used with your configuration.
|
|
|
|
If the running version of OpenTofu doesn't match the constraints specified,
|
|
OpenTofu will produce an error and exit without taking any further actions.
|
|
|
|
When you use [child modules](../../language/modules/index.mdx), each module can specify its own
|
|
version requirements. The requirements of all modules in the tree must be
|
|
satisfied.
|
|
|
|
Use OpenTofu version constraints in a collaborative environment to
|
|
ensure that everyone is using a specific OpenTofu version, or using at least
|
|
a minimum OpenTofu version that has behavior expected by the configuration.
|
|
|
|
The `required_version` setting applies only to the version of OpenTofu CLI.
|
|
OpenTofu's resource types are implemented by provider plugins,
|
|
whose release cycles are independent of OpenTofu CLI and of each other.
|
|
Use [the `required_providers` block](../../language/providers/requirements.mdx) to manage
|
|
the expected versions for each provider you use.
|
|
|
|
## Specifying Provider Requirements
|
|
|
|
The `required_providers` block specifies all of the providers required by the
|
|
current module, mapping each local provider name to a source address and a
|
|
version constraint.
|
|
|
|
```hcl
|
|
terraform {
|
|
required_providers {
|
|
aws = {
|
|
version = ">= 2.7.0"
|
|
source = "hashicorp/aws"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
For more information, see [Provider Requirements](../../language/providers/requirements.mdx).
|
|
|
|
## Experimental Language Features
|
|
|
|
The OpenTofu team will sometimes introduce new language features initially via
|
|
an opt-in experiment, so that the community can try the new feature and give
|
|
feedback on it prior to it becoming a backward-compatibility constraint.
|
|
|
|
In releases where experimental features are available, you can enable them on
|
|
a per-module basis by setting the `experiments` argument inside a `tofu`
|
|
block:
|
|
|
|
```hcl
|
|
terraform {
|
|
experiments = [example]
|
|
}
|
|
```
|
|
|
|
The above would opt in to an experiment named `example`, assuming such an
|
|
experiment were available in the current OpenTofu version.
|
|
|
|
Experiments are subject to arbitrary changes in later releases and, depending on
|
|
the outcome of the experiment, may change drastically before final release or
|
|
may not be released in stable form at all. Such breaking changes may appear
|
|
even in minor and patch releases. We do not recommend using experimental
|
|
features in OpenTofu modules intended for production use.
|
|
|
|
In order to make that explicit and to avoid module callers inadvertently
|
|
depending on an experimental feature, any module with experiments enabled will
|
|
generate a warning on every `tofu plan` or `tofu apply`. If you
|
|
want to try experimental features in a shared module, we recommend enabling the
|
|
experiment only in alpha or beta releases of the module.
|
|
|
|
The introduction and completion of experiments is reported in
|
|
[OpenTofu's changelog](https://github.com/opentofu/opentofu/blob/main/CHANGELOG.md),
|
|
so you can watch the release notes there to discover which experiment keywords,
|
|
if any, are available in a particular OpenTofu release.
|
|
|
|
## Passing Metadata to Providers
|
|
|
|
The `terraform` block can have a nested `provider_meta` block for each
|
|
provider a module is using, if the provider defines a schema for it. This
|
|
allows the provider to receive module-specific information, and is primarily
|
|
intended for modules distributed by the same vendor as the associated provider.
|
|
|
|
For more information, see [Provider Metadata](../../internals/provider-meta.mdx).
|