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 (#241)

Browse Source 
Signed-off-by: Marcin Białoń <mbialon@spacelift.io>
This commit is contained in:
Marcin Białoń 2023-08-30 00:01:20 +02:00 committed by GitHub
parent 566749d817
commit 8374badd13
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 169 additions and 196 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
website/docs/language/attr-as-blocks.mdx
View File

@ -9,7 +9,7 @@ description: >-
# Attributes as Blocks
-> **Note:** This page is an appendix to the Terraform documentation. Most users do not need to know the full details of this behavior.
-> **Note:** This page is an appendix to the OpenTF documentation. Most users do not need to know the full details of this behavior.
## Summary
@ -23,14 +23,14 @@ is set to an empty list (`<ATTR> = []`).
Most users do not need to know any further details of this "nested block or
empty list" behavior. However, read further if you need to:
- Use Terraform's [JSON syntax](/terraform/language/syntax/json) with this
- Use OpenTF's [JSON syntax](/opentf/language/syntax/json) with this
type of resource.
- Create a reusable module that wraps this type of resource.
## Details
In Terraform v0.12 and later, the language makes a distinction between
[argument syntax and nested block syntax](/terraform/language/syntax/configuration#arguments-and-blocks)
The language makes a distinction between
[argument syntax and nested block syntax](/opentf/language/syntax/configuration#arguments-and-blocks)
within blocks:
- Argument syntax sets a named argument for the containing object. If the
@ -44,24 +44,11 @@ within blocks:
merging in with any explicitly-defined arguments.
The distinction between these is particularly important for
[JSON syntax](/terraform/language/syntax/json)
[JSON syntax](/opentf/language/syntax/json)
because the same primitive JSON constructs (lists and objects) will be
interpreted differently depending on whether a particular name is an argument
or a nested block type.
However, in some cases existing provider features were relying on the
conflation of these two concepts in the language of Terraform v0.11 and earlier,
using nested block syntax in most cases but using argument syntax to represent
explicitly the idea of removing all existing objects of that type, since the
absence of any blocks was interpreted as "ignore any existing objects".
The information on this page only applies to certain special arguments that
were relying on this usage pattern prior to Terraform v0.12. The documentation
for each of those features links to this page for details of the special usage
patterns that apply. In all other cases, use either argument or nested block
syntax as directed by the examples in the documentation for a particular
resource type.
## Defining a Fixed Object Collection Value
When working with resource type arguments that behave in this way, it is valid
@ -151,7 +138,7 @@ example = [
For the arguments that use the attributes-as-blocks usage mode, the above is
a better pattern than using
[`dynamic` blocks](/terraform/language/expressions/dynamic-blocks)
[`dynamic` blocks](/opentf/language/expressions/dynamic-blocks)
because the case where the
caller provides an empty list will result in explicitly assigning an empty
list value, rather than assigning no value at all and thus retaining and
@ -161,7 +148,7 @@ dynamically-generating _normal_ nested blocks, though.
## In JSON syntax
Arguments that use this special mode are specified in JSON syntax always using
the [JSON expression mapping](/terraform/language/syntax/json#expression-mapping)
the [JSON expression mapping](/opentf/language/syntax/json#expression-mapping)
to produce a list of objects.
The interpretation of these values in JSON syntax is, therefore, equivalent

40
website/docs/language/index.mdx
View File

@ -1,35 +1,31 @@
---
page_title: Overview - Configuration Language
description: >-
Use the Terraform configuration language to describe the infrastructure that Terraform manages.
Use the OpenTF configuration language to describe the infrastructure that OpenTF manages.
---
# Terraform Language Documentation
# OpenTF Language Documentation
This is the documentation for Terraform's configuration language. It is relevant
to users of [Terraform CLI](/terraform/cli),
[Terraform Cloud](https://cloud.hashicorp.com/products/terraform), and
[Terraform Enterprise](/terraform/enterprise). Terraform's language is
its primary user interface. Configuration files you write in Terraform
language tell Terraform what plugins to install, what infrastructure to create,
and what data to fetch. Terraform language also lets you define dependencies
This is the documentation for OpenTF's configuration language. It is relevant
to users of [OpenTF CLI](/opentf/cli), and TACOS (TF Automation and Collaboration Software).
OpenTF's language is its primary user interface. Configuration files you write in OpenTF
language tell OpenTF what plugins to install, what infrastructure to create,
and what data to fetch. OpenTF language also lets you define dependencies
between resources and create multiple similar resources from a single
configuration block.
> **Hands-on:** Try the [Write Terraform Configuration](/terraform/tutorials/configuration-language) tutorials.
## About the OpenTF Language
## About the Terraform Language
The main purpose of the Terraform language is declaring
[resources](/terraform/language/resources), which represent infrastructure objects. All other
The main purpose of the OpenTF language is declaring
[resources](/opentf/language/resources), which represent infrastructure objects. All other
language features exist only to make the definition of resources more flexible
and convenient.
A _Terraform configuration_ is a complete document in the Terraform language
that tells Terraform how to manage a given collection of infrastructure. A
An _OpenTF configuration_ is a complete document in the OpenTF language
that tells OpenTF how to manage a given collection of infrastructure. A
configuration can consist of multiple files and directories.
The syntax of the Terraform language consists of only a few basic elements:
The syntax of the OpenTF language consists of only a few basic elements:
```hcl
resource "aws_vpc" "main" {
@ -45,16 +41,16 @@ resource "aws_vpc" "main" {
- _Blocks_ are containers for other content and usually represent the
configuration of some kind of object, like a resource. Blocks have a
_block type,_ can have zero or more _labels,_ and have a _body_ that contains
any number of arguments and nested blocks. Most of Terraform's features are
any number of arguments and nested blocks. Most of OpenTF's features are
controlled by top-level blocks in a configuration file.
- _Arguments_ assign a value to a name. They appear within blocks.
- _Expressions_ represent a value, either literally or by referencing and
combining other values. They appear as values for arguments, or within other
expressions.
The Terraform language is declarative, describing an intended goal rather than
The OpenTF language is declarative, describing an intended goal rather than
the steps to reach that goal. The ordering of blocks and the files they are
organized into are generally not significant; Terraform only considers implicit
organized into are generally not significant; OpenTF only considers implicit
and explicit relationships between resources when determining an order of
operations.
@ -62,7 +58,7 @@ operations.
The following example describes a simple network topology for Amazon Web
Services, just to give a sense of the overall structure and syntax of the
Terraform language. Similar configurations can be created for other virtual
OpenTF language. Similar configurations can be created for other virtual
network services, using resource types defined by other providers, and a
practical network configuration will often contain additional elements not
shown here.
@ -106,7 +102,7 @@ resource "aws_subnet" "az" {
# For each subnet, use one of the specified availability zones.
availability_zone = var.availability_zones[count.index]
# By referencing the aws_vpc.main object, Terraform knows that the subnet
# By referencing the aws_vpc.main object, OpenTF knows that the subnet
# must be created only after the VPC is created.
vpc_id = aws_vpc.main.id

298
website/docs/language/v1-compatibility-promises.mdx
View File

@ -1,28 +1,27 @@
---
page_title: Terraform v1.x Compatibility Promises
page_title: OpenTF v1.x Compatibility Promises
description: |-
From Terraform v1.0 onwards the Terraform team promises to preserve backward
compatibility for most of the Terraform language and the primary CLI
From OpenTF v1.6 onwards the OpenTF team promises to preserve backward
compatibility for most of the OpenTF language and the primary CLI
workflow, until the next major release.
---
# Terraform v1.x Compatibility Promises
# OpenTF v1.x Compatibility Promises
The release of Terraform v1.0 represents an important milestone in the
development of the Terraform language and workflow. Terraform v1.0 is a stable
The release of OpenTF v1.6 represents an important milestone in the
development of the OpenTF language and workflow. OpenTF v1.x is a stable
platform for describing and managing infrastructure.
In this release we're defining a number of Terraform behaviors that we intend
In this release we're defining a number of OpenTF behaviors that we intend
to remain compatible with throughout the 1.x releases:
* A large subset of Terraform language features.
* A more conservative subset of the Terraform CLI workflow commands.
* The wire protocol for communication between Terraform Core and Terraform
* A large subset of OpenTF language features.
* A more conservative subset of the OpenTF CLI workflow commands.
* The wire protocol for communication between OpenTF Core and OpenTF
providers.
* The wire protocols for installation of Terraform providers and external
Terraform modules.
* The wire protocols for installation of providers and external modules.
Our intention is that Terraform modules written for Terraform v1.0 will
Our intention is that modules written for OpenTF v1.6 will
continue to plan and apply successfully, without required changes, throughout
the v1.x releases.
@ -30,89 +29,89 @@ We also intend that automation built around the workflow subset described in
this document will work without changes in all future v1.x releases.
Finally, we intend that providers built against the currently-documented
provider wire protocol will be compatible with all future Terraform v1.x
provider wire protocol will be compatible with all future OpenTF v1.x
releases targeting the same operating system and architecture, without the
need for source code modification or binary recompilation.
In short, we aim to make upgrades between v1.x releases straightforward,
requiring no changes to your configuration, no extra commands to run upgrade
steps, and no changes to any automation you've set up around Terraform.
steps, and no changes to any automation you've set up around OpenTF.
The Terraform v1.x series will be actively maintained for at least 18 months
after v1.0.
The OpenTF v1.x series will be actively maintained for at least 18 months
after v1.6.
The following sections include some specific guidance on what we will promise
throughout the v1.x series, for those who would like full details. At
a higher level though, we don't intend to make any changes that would cause
existing modules or automation to require changes when upgrading to a new
v1.x release. We will generally treat compatibility problems in new Terraform
v1.x release. We will generally treat compatibility problems in new OpenTF
CLI releases as bugs to be fixed unless there was a very significant
justification for the change, such as in addressing a critical security
problem or matching with a breaking change to a remote dependency that isn't
directly under our control.
## The Terraform Language
## The OpenTF Language
The main Terraform Language includes the language syntax, the top-level
The main OpenTF Language includes the language syntax, the top-level
structures such as `resource`, `module`, and `provider` blocks, the
"meta-arguments" in those blocks, and the documented semantics and behaviors
for the operators and built-in functions available for use in expressions.
There is not a single formal specification for the Terraform language, but the
Configuration section of the documentation on the Terraform website serves as a
There is not a single formal specification for the OpenTF language, but the
Configuration section of the documentation on the OpenTF website serves as a
description of the language features and their intended behaviors.
The following top-level blocks and their defined "meta-arguments" (that is,
arguments defined by Terraform Core rather than by external plugins such as
arguments defined by OpenTF Core rather than by external plugins such as
providers) will retain their current functionality:
* [`resource`](/terraform/language/resources) and
[`data`](/terraform/language/data-sources) blocks to
* [`resource`](/opentf/language/resources) and
[`data`](/opentf/language/data-sources) blocks to
declare resources, including their nested block types `lifecycle`,
`connection`, and `provisioner`, and their meta-argument `provider`.
* [`module`](/terraform/language/modules/syntax) blocks to call other modules,
* [`module`](/opentf/language/modules/syntax) blocks to call other modules,
and its meta-argument `providers`.
* The [`count`](/terraform/language/meta-arguments/count),
[`for_each`](/terraform/language/meta-arguments/for_each), and
[`depends_on`](/terraform/language/meta-arguments/depends_on) meta-arguments
* The [`count`](/opentf/language/meta-arguments/count),
[`for_each`](/opentf/language/meta-arguments/for_each), and
[`depends_on`](/opentf/language/meta-arguments/depends_on) meta-arguments
in `resource`, `data`, and `module` blocks.
* [`provider`](/terraform/language/providers/configuration) blocks to configure
* [`provider`](/opentf/language/providers/configuration) blocks to configure
providers, and the `alias` meta-argument.
* [`variable`](/terraform/language/values/variables#declaring-an-input-variable),
[`output`](/terraform/language/values/outputs#declaring-an-output-value), and
[`locals`](/terraform/language/values/locals#declaring-a-local-value) blocks
* [`variable`](/opentf/language/values/variables#declaring-an-input-variable),
[`output`](/opentf/language/values/outputs#declaring-an-output-value), and
[`locals`](/opentf/language/values/locals#declaring-a-local-value) blocks
for declaring the various kinds of named values in a module.
* [`terraform`](/terraform/language/settings) blocks, including the nested
[`required_version`](/terraform/language/settings#specifying-a-required-terraform-version)
* [`terraform`](/opentf/language/settings) blocks, including the nested
[`required_version`](/opentf/language/settings#specifying-a-required-opentf-version)
and
[`required_providers`](/terraform/language/providers/requirements#requiring-providers)
[`required_providers`](/opentf/language/providers/requirements#requiring-providers)
arguments, and nested
[`backend`](/terraform/language/settings/backends/configuration#using-a-backend-block)
[`backend`](/opentf/language/settings/backends/configuration#using-a-backend-block)
blocks for backend configuration.
We also intend to keep compatibility with all
[expression operators](/terraform/language/expressions) and
[built-in functions](/terraform/language/functions), with the exception of
[expression operators](/opentf/language/expressions) and
[built-in functions](/opentf/language/functions), with the exception of
references to
[`terraform.workspace`](/terraform/language/expressions/references#terraform-workspace),
[`terraform.workspace`](/opentf/language/expressions/references#terraform-workspace),
whose behavior may change as part of future changes to the workspace model.
We intend to retain broad compatibility with Terraform language features, with
We intend to retain broad compatibility with OpenTF language features, with
a few specific caveats:
* We consider a configuration to be valid if Terraform can create and apply
* We consider a configuration to be valid if OpenTF can create and apply
a plan for it without reporting any errors.
A configuration that currently produces errors might generate different
errors or exhibit other non-error behaviors in a future version of
Terraform. A configuration that generates errors during the apply phase
OpenTF. A configuration that generates errors during the apply phase
might generate similar errors at an earlier phase in future, because
we generally consider it better to detect errors in as early a phase as
possible.
Generally-speaking, the compatibility promises described in this document
apply only to valid configurations. Handling of invalid configurations is
always subject to change in future Terraform releases.
always subject to change in future OpenTF releases.
* If the actual behavior of a feature differs from what we explicitly
documented as the feature's behavior, we will usually treat that as a bug
and change the feature to match the documentation, although we will avoid
@ -120,23 +119,23 @@ a few specific caveats:
We cannot promise to always remain "bug-compatible" with previous releases,
but we will consider such fixes carefully to minimize their impact.
* Any experimental features may change or may be removed entirely from future
releases. Terraform always produces a warning when an experimental language
releases. OpenTF always produces a warning when an experimental language
feature is active, to make you aware of that risk. We don't recommend using
experimental features in production modules.
* We will introduce new language features, and if you start using them then
your configuration won't work with prior Terraform versions that didn't
your configuration won't work with prior OpenTF versions that didn't
support those features yet.
* Terraform Providers are separate plugins which can change independently of
Terraform Core and are therefore not subject to these compatibility promises.
* Providers are separate plugins which can change independently of
OpenTF Core and are therefore not subject to these compatibility promises.
If you upgrade any of the providers you are using then you might need to
change provider or resource configurations related to those providers.
* A small number of features remain deprecated with explicit warnings in
Terraform v1.0. Those deprecation cycles will end in a future v1.x release,
OpenTF v1.6. Those deprecation cycles will end in a future v1.x release,
at which point we will remove the corresponding features.
## Workflow
There is a set of often used Terraform workflows, which we are calling
There is a set of often used OpenTF workflows, which we are calling
_protected workflows_. We will not remove these commands, subcommands, and
flags or make backward-incompatible changes to protected workflow
functionality. If we accidentally change these, we will consider
@ -147,74 +146,74 @@ There is another set of commands that we are explicitly _not_ making
compatibility promises about, because we expect their functionality to change
in v1.x releases: see [Commands That Might Change](#commands-that-might-change).
The supported ways for external software to interact with Terraform are via
The supported ways for external software to interact with OpenTF are via
the JSON output modes offered by some commands and via exit status codes.
We may extend certain JSON formats with new object properties but we will not
remove or make breaking changes to the definitions of existing properties.
Natural language command output or log output is not a stable interface and
may change in any new version. If you write software that parses this output
then it may need to be updated when you upgrade Terraform. If you need access
then it may need to be updated when you upgrade OpenTF. If you need access
to data that is not currently available via one of the machine-readable JSON
interfaces, we suggest opening a feature request to discuss your use-case.
## Upgrading and Downgrading
Throughout the v1.x series of releases, we intend that you should be able to
switch to a newer Terraform version and use it just as before, without any
switch to a newer OpenTF version and use it just as before, without any
special upgrade steps.
You should be able to upgrade from any v1.x release to any later v1.x release.
You might also be able to downgrade to an earlier v1.x release, but that isn't
guaranteed: later releases may introduce new features that earlier versions
cannot understand, including new storage formats for Terraform state snapshots.
cannot understand, including new storage formats for OpenTF state snapshots.
If you make use of features introduced in a later v1.x release, your
configuration won't be compatible with releases that predate that feature.
For example, if a language feature is added in v1.3 and you start using it, your
Terraform configuration will no longer be compatible with Terraform v1.2.
For example, if a language feature is added in v1.7 and you start using it, your
OpenTF configuration will no longer be compatible with OpenTF v1.6.
## Providers
Terraform providers are separate plugins which communicate with Terraform using
OpenTF providers are separate plugins which communicate with OpenTF using
a documented protocol. Therefore these compatibility promises can only cover
the "client" side of this protocol as implemented by Terraform Core; the
the "client" side of this protocol as implemented by OpenTF Core; the
behaviors of individual providers, including which resource types they support
and which arguments they expect, are decided by the provider development teams
and can change independently of Terraform Core releases.
and can change independently of OpenTF Core releases.
If you upgrade to a new version of a provider then you might need to change
the parts of your configuration which are interpreted by that provider, even
if you are still using a Terraform v1.x release.
if you are still using a OpenTF v1.x release.
### Provider Installation Methods
Terraform normally installs providers from a provider registry implementing
[the Provider Registry Protocol](/terraform/internals/provider-registry-protocol),
version 1. All Terraform v1.x releases will remain compatible with that
OpenTF normally installs providers from a provider registry implementing
[the Provider Registry Protocol](/opentf/internals/provider-registry-protocol),
version 1. All OpenTF v1.x releases will remain compatible with that
protocol, and so correctly-implemented provider registries will stay compatible.
Terraform also supports installation of providers from
[local filesystem directories](/terraform/cli/config/config-file#filesystem_mirror)
OpenTF also supports installation of providers from
[local filesystem directories](/opentf/cli/config/config-file#filesystem_mirror)
(filesystem mirrors) and from
[network mirrors](/terraform/cli/config/config-file#network_mirror)
(implementing [the Provider Mirror Protocol](/terraform/internals/provider-network-mirror-protocol).
All Terraform v1.x releases will remain compatible with those installation
[network mirrors](/opentf/cli/config/config-file#network_mirror)
(implementing [the Provider Mirror Protocol](/opentf/internals/provider-network-mirror-protocol).
All OpenTF v1.x releases will remain compatible with those installation
methods, including
[the Implied Local Mirror Directories](/terraform/cli/config/config-file#implied-local-mirror-directories).
[the Implied Local Mirror Directories](/opentf/cli/config/config-file#implied-local-mirror-directories).
Specific provider registries or network mirrors are run independently from
Terraform itself and so their own behaviors are not subject to these
OpenTF itself and so their own behaviors are not subject to these
compatibility promises.
### Provider Protocol Versions
The current major version of the provider plugin protocol as of Terraform v1.0
The current major version of the provider plugin protocol as of OpenTF v1.6
is version 5, which is defined by a combination of a Protocol Buffers schema
describing the physical wire formats and by additional prose documentation
describing the expected provider behaviors.
We will support protocol version 5 throughout the Terraform v1.x releases. If
We will support protocol version 5 throughout the OpenTF v1.x releases. If
we make new minor revisions to protocol version 5 in later releases then we
will design them such that existing plugins will continue to work, as long as
they correctly implemented the protocol.
@ -223,73 +222,69 @@ We may introduce new major versions of the protocol during the v1.x series. If
so, we will continue to support protocol version 5 alongside those new versions.
Individual provider teams might decide to remove support for protocol version 5
in later releases, in which case those new provider releases will not be
compatible with all of the Terraform v1.x releases.
compatible with all of the OpenTF v1.x releases.
## External Modules
Terraform modules are reusable infrastructure components written in the
Terraform language. Some modules are "external" in the sense that Terraform
Modules are reusable infrastructure components written in the
OpenTF language. Some modules are "external" in the sense that OpenTF
automatically installs them from a location other than the current
configuration directory, in which case their contents could change
independently of changes to your local modules, of the providers you use,
and of Terraform itself.
and of OpenTF itself.
### Module Installation Methods
Terraform supports installing child modules from a number of different
[module source types](/terraform/language/modules/sources). We will continue
OpenTF supports installing child modules from a number of different
[module source types](/opentf/language/modules/sources). We will continue
to support all of the existing source types throughout the v1.x releases.
One of the supported source types is a module registry implementing
[the Module Registry Protocol](/terraform/internals/module-registry-protocol)
version 1. All Terraform v1.x releases will remain compatible with correct
[the Module Registry Protocol](/opentf/internals/module-registry-protocol)
version 1. All OpenTF v1.x releases will remain compatible with correct
implementations of that protocol.
Some module source types work directly with services or protocols defined and
run by third parties. Although we will not remove Terraform's own client-side
run by third parties. Although we will not remove OpenTF's own client-side
support for those, we cannot guarantee that their owners will keep those
services running or that they will remain compatible with Terraform's client
services running or that they will remain compatible with OpenTF's client
implementations.
### External Module Compatibility
If your configuration depends on external modules, newer versions of those
modules may include breaking changes. External modules are not part of
Terraform and are therefore not subject to these compatibility promises.
OpenTF and are therefore not subject to these compatibility promises.
## Provisioners
We will maintain compatibility for the `file`, `local-exec`, and `remote-exec`
provisioner types through all v1.x releases.
Some additional vendor-specific provisioners were available in earlier
Terraform versions but were deprecated in Terraform v0.13 and removed in
Terraform v0.15.
Terraform supports loading additional provisioners as plugins from certain
OpenTF supports loading additional provisioners as plugins from certain
local filesystem directories. We'll continue to support that throughout the
Terraform v1.x releases, but since such plugins are separate from Terraform
OpenTF v1.x releases, but since such plugins are separate from OpenTF
Core itself their own behaviors cannot be subject to these compatibility
promises. However, we will continue to support the plugin wire protocol as
defined in Terraform v1.0 throughout the v1.x releases, and so
defined in OpenTF v1.6 throughout the v1.x releases, and so
correctly-implemented provisioner plugins should remain compatible with future
Terraform releases.
OpenTF releases.
## State Storage Backends
When you use _remote state_, Terraform interacts with remote services over
the network in order to store and manage locks for Terraform state.
When you use _remote state_, OpenTF interacts with remote services over
the network in order to store and manage locks for OpenTF state.
For historical reasons, all supported state storage backends are included as
part of Terraform CLI but not all are supported directly by the Terraform
Team. Only the following backends maintained by the Terraform team are subject
part of OpenTF CLI but not all are supported directly by the OpenTF
Team. Only the following backends maintained by the OpenTF team are subject
to compatibility promises:
* `local` (the default, when you are not using remote state)
* `http`
The other state storage backends are maintained by external teams via
contributions to the Terraform CLI codebase, and so their expected
contributions to the OpenTF CLI codebase, and so their expected
configuration arguments or behaviors might change even in v1.x releases,
although we will aim to still ensure a good migration path in such cases,
where possible.
@ -298,17 +293,12 @@ We are considering allowing external state storage backend implementations
via plugins, similar to provider plugins. If we introduce such a mechanism
during the v1.x releases then you may need to make configuration changes in
order to use those plugins, and state storage backends other than those
listed above may be removed from later versions of Terraform CLI once
listed above may be removed from later versions of OpenTF CLI once
equivalent plugins are available.
### The `remote` Backend and Terraform Cloud
### The `remote` Backend
The `remote` backend is maintained by the Terraform Cloud team and so its
behavior may change along with ongoing changes to Terraform Cloud.
There will be a supported mechanism to use Terraform CLI with Terraform Cloud
throughout the v1.x releases, but the exact details may change. Terraform Cloud
evolves independently of Terraform CLI and is therefore not subject to these
The `remote` backend's behavior may change along the way and is therefore not subject to these
compatibility promises.
## Community-maintained State Storage Backends
@ -326,7 +316,7 @@ contributors and are not subject to these compatibility promises.
### Unmaintained State Storage Backends
The `artifactory`, `etcdv2`, `manta`, and `swift` state storage backends do not
currently have any maintainers and thus remain in Terraform CLI releases on
currently have any maintainers and thus remain in OpenTF CLI releases on
a best-effort basis. They may be removed in later v1.x releases, and will not
be updated in case of any breaking changes to the services they integrate with.
@ -341,23 +331,23 @@ releases of these operating systems:
* Linux on x64, 32-bit ARMv6, and 64-bit ARMv8 (`linux_amd64`, `linux_arm`, and `linux_arm64` respectively)
Over time we may require newer versions of these operating systems. For
example, subsequent Terraform releases in the v1.x series might end support
example, subsequent OpenTF releases in the v1.x series might end support
for earlier versions of macOS or Windows, or earlier Linux kernel releases.
We have historically produced official releases for a number of other platforms
as a convenience to users of those platforms, and we have no current plans to
stop publishing them but we cannot promise ongoing releases or bug fixes for
the other platforms throughout the v1.x series. We do not routinely test
Terraform on any platforms other than those listed above.
OpenTF on any platforms other than those listed above.
We might add support for new platforms in later v1.x releases. If so, earlier
Terraform releases prior to that support will not be available on those
OpenTF releases prior to that support will not be available on those
platforms.
All Terraform plugins, including provider plugins, are separate programs that
All OpenTF plugins, including provider plugins, are separate programs that
have their own policies for which platforms they support. We cannot guarantee
that all providers currently support or will continue to support the platforms
listed above, even though Terraform CLI itself will support them.
listed above, even though OpenTF CLI itself will support them.
## Later Revisions to These Promises
@ -379,7 +369,7 @@ stated.
### Protected Workflow Commands
The following is the list of Terraform CLI subcommands and options that are
The following is the list of OpenTF CLI subcommands and options that are
subject to these compatibility promises. If you build automation around
these commands then it should be compatible with all later v1.x releases.
@ -387,7 +377,7 @@ As noted above, compatibility with external software is limited to
explicitly-machine-readable output (`-json` and `-raw` modes) and exit codes.
Any natural-language output from these commands might change in later releases.
* [`init`](/terraform/cli/commands/init)
* [`init`](/opentf/cli/commands/init)
* `-backend=false`
* `-backend-config=FILE`
* `-backend-config="KEY=VALUE"`
@ -399,10 +389,10 @@ Any natural-language output from these commands might change in later releases.
* `-plugin-dir=DIR`
* `-reconfigure`
* `-upgrade`
* [`validate`](/terraform/cli/commands/validate)
* [`validate`](/opentf/cli/commands/validate)
* `-json`
* `-no-color`
* [`plan`](/terraform/cli/commands/plan)
* [`plan`](/opentf/cli/commands/plan)
* `-compact-warnings`
* `-destroy`
* `-detailed-exitcode`
@ -419,7 +409,7 @@ Any natural-language output from these commands might change in later releases.
* `-target=ADDRESS`
* `-var 'NAME=VALUE'`
* `-var-file=FILE`
* [`apply`](/terraform/cli/commands/apply)
* [`apply`](/opentf/cli/commands/apply)
* `-auto-approve`
* `-compact-warnings`
* `-lock=false`
@ -434,64 +424,64 @@ Any natural-language output from these commands might change in later releases.
* `-target=ADDRESS`
* `-var 'NAME=VALUE'`
* `-var-file=FILE`
* [`show`](/terraform/cli/commands/show)
* [`show`](/opentf/cli/commands/show)
* `-no-color`
* `-json`
* (both with and without a plan file)
* [`providers`](/terraform/cli/commands/providers) (with no subcommand)
* [`providers lock`](/terraform/cli/commands/providers/lock)
* [`providers`](/opentf/cli/commands/providers) (with no subcommand)
* [`providers lock`](/opentf/cli/commands/providers/lock)
* `-fs-mirror=PATH`
* `-net-mirror=URL`
* `-platform=OS_ARCH`
* [`providers mirror`](/terraform/cli/commands/providers/mirror)
* [`providers mirror`](/opentf/cli/commands/providers/mirror)
* `-platform=OS_ARCH`
* [`providers schema`](/terraform/cli/commands/providers/schema)
* [`providers schema`](/opentf/cli/commands/providers/schema)
* `-json`
* [`fmt`](/terraform/cli/commands/fmt)
* [`fmt`](/opentf/cli/commands/fmt)
* `-list=false`
* `-write=false`
* `-diff`
* `-recursive`
* `-check`
* [`version`](/terraform/cli/commands/version)
* [`version`](/opentf/cli/commands/version)
* `-json`
* [`output`](/terraform/cli/commands/output)
* [`output`](/opentf/cli/commands/output)
* `-no-color`
* `-json`
* `-raw`
* [`taint`](/terraform/cli/commands/taint)
* [`taint`](/opentf/cli/commands/taint)
* `-allow-missing`
* `-lock=false`
* `-lock-timeout=DURATION`
* `-ignore-remote-version`
* [`untaint`](/terraform/cli/commands/untaint)
* [`untaint`](/opentf/cli/commands/untaint)
* `-allow-missing`
* `-lock=false`
* `-lock-timeout=DURATION`
* `-ignore-remote-version`
* [`force-unlock`](/terraform/cli/commands/force-unlock)
* [`force-unlock`](/opentf/cli/commands/force-unlock)
* `-force`
* [`state list`](/terraform/cli/commands/state/list)
* [`state list`](/opentf/cli/commands/state/list)
* `-id=ID`
* [`state pull`](/terraform/cli/commands/state/pull)
* [`state push`](/terraform/cli/commands/state/push)
* [`state pull`](/opentf/cli/commands/state/pull)
* [`state push`](/opentf/cli/commands/state/push)
* `-force`
* `-lock=false`
* `-lock-timeout=DURATION`
* [`state show`](/terraform/cli/commands/state/show)
* [`state show`](/opentf/cli/commands/state/show)
* `-ignore-remote-version`
* [`login`](/terraform/cli/commands/login)
* [`login`](/opentf/cli/commands/login)
For commands or options not in the above list, we will still avoid breaking
changes where possible, but can't promise full compatibility throughout the
v1.x series. If you are building automation around Terraform, use only the
v1.x series. If you are building automation around OpenTF, use only the
commands above to avoid the need for changes when upgrading.
Please note that although Terraform's internal logs (via the `TF_LOG`
Please note that although OpenTF's internal logs (via the `TF_LOG`
environment variable) are available in a JSON format, the particular syntax
or structure of those log lines is _not_ a supported integration interface.
The logs are available as JSON only to help with ad-hoc filtering and
processing of logs by Terraform developers.
processing of logs by OpenTF developers.
### Commands That Might Change
@ -500,18 +490,18 @@ to compatibility promises, either because we have existing plans to improve
them during the v1.x series or because we are aware of shortcomings in their
design that might require breaking changes for ongoing maintenence.
While you can freely use these commands when running Terraform interactively
While you can freely use these commands when running OpenTF interactively
as long as they remain supported, we don't recommend using them as part of
any automation unless you are willing to potentially update that automation
when upgrading to a later v1.x release.
* `destroy` (consider `terraform apply -destroy` instead)
* `destroy` (consider `opentf apply -destroy` instead)
* `console`
* `get` (consider `terraform init` instead)
* `get` (consider `opentf init` instead)
* `graph`
* `import`
* `push`
* `refresh` (consider `terraform apply -refresh-only` instead)
* `refresh` (consider `opentf apply -refresh-only` instead)
* `state mv`
* `state replace-provider`
* `state rm`
@ -525,11 +515,11 @@ command names or options used to meet those use-cases.
### Automated Regression Testing
The Terraform codebase includes various unit and integration tests intended to
The OpenTF codebase includes various unit and integration tests intended to
help us to notice accidental behavior regressions before they ship in a stable
version.
However, Terraform is a relatively complex system with many different features
However, OpenTF is a relatively complex system with many different features
that can interact in interesting ways. In the past we've seen reports of
behavior differences that appeared only when combining two or more features in
a way we hadn't previously anticipated or written automated tests for.
@ -537,7 +527,7 @@ a way we hadn't previously anticipated or written automated tests for.
In each case we have both implemented a change to resolve the compatibility
problem _and_ added one or more integration tests representing the behavior
of that combination of features. We intend to continue this approach, so we can
improve Terraform's test coverage over time.
improve OpenTF's test coverage over time.
### Prerelease Versions
@ -571,7 +561,7 @@ releases by proactively testing modules against alpha, beta, and release
candidate packages. We recommend doing so only in isolated development or
staging environments rather than against your production infrastructure. If you
find a change in behavior in a prerelease build that seems contrary to the
promises in this document, please open an issue in Terraform's GitHub
promises in this document, please open an issue in OpenTF's GitHub
repository to discuss it.
### Late-reported Regressions
@ -587,17 +577,17 @@ make this decision with due consideration to the implications of each unique
situation.
You can minimize the risk of your modules being affected by late-reported
regressions by upgrading promptly to new minor and patch releases of Terraform
and reporting any compatibility problems you encounter in Terraform's GitHub
regressions by upgrading promptly to new minor and patch releases of OpenTF
and reporting any compatibility problems you encounter in OpenTF's GitHub
repository.
### Pragmatic Exceptions
We are making the promises above in good faith, with the intent that your
investment in writing Terraform modules or automation will not be invalidated
by future changes to Terraform. However, broad promises like the above can't
investment in writing OpenTF modules or automation will not be invalidated
by future changes to OpenTF. However, broad promises like the above can't
possibly cover all nuances of practical problems that might arise as we
continue to develop Terraform.
continue to develop OpenTF.
For that reason, there are some situations where we may still need to make
changes that may impact existing modules or automation:
@ -605,13 +595,13 @@ changes that may impact existing modules or automation:
* Security problems: We may become aware of a design problem that has an
important security impact. Depending on our determination of the associated
risk, we may choose to break compatibility to achieve a more secure system.
* External Dependencies: Terraform's behavior depends on interfaces provided
* External Dependencies: OpenTF's behavior depends on interfaces provided
by external codebases, including your chosen operating system and including
some remote network services for situations such as module and provider
installation. These external systems can change outside of our control,
including potentially removing or changing features that Terraform's own
including potentially removing or changing features that OpenTF's own
features depend on. In that case, if there is no suitable replacement
mechanism then we may need to change Terraform's design to work within the
mechanism then we may need to change OpenTF's design to work within the
new constraints.
* Opt-in Compatibility Breaks: The design of a language new feature may require
changing the behavior or configuration representation of an existing feature.
@ -619,7 +609,7 @@ changes that may impact existing modules or automation:
breaking existing modules, but if you change your module to opt in to the
new feature then you may also then be required to change other parts of your
configuration to work with the new language design.
* Bugs in New Features: If we introduce a new feature to Terraform and the
* Bugs in New Features: If we introduce a new feature to OpenTF and the
initial implementation has problems that cause it to not match the documented
design intent at release, we may make a follow-up release that corrects
the implementation to match the documented design, even if that represents
@ -627,7 +617,7 @@ changes that may impact existing modules or automation:
However, once a feature is well-established and in common use we will usually
defer to the implemented behavior and instead change the documentation to
reflect it.
* Regressions in Existing Features: If we learn that a new Terraform release
* Regressions in Existing Features: If we learn that a new OpenTF release
includes a regression for an existing feature that wasn't detected during
the development and prerelease periods, and that learning comes promptly
after the new release, we will typically restore the previous behavior at
@ -643,10 +633,10 @@ changes that may impact existing modules or automation:
affects then we may choose to accept the regression as the new promised
behavior.
* Situations we cannot anticipate: Although we've made an effort to consider
various specific exceptional situations here, Terraform and its development
various specific exceptional situations here, OpenTF and its development
process are not isolated from broader context, and so we must consider that
there may be situations that we cannot possibly anticipate that would affect
the future of Terraform. In those situations, we will always do our best to
the future of OpenTF. In those situations, we will always do our best to
find a course of action that will minimize as much as possible the impact to
existing modules and automation.