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/state (#236)

Browse Source 
Signed-off-by: Marcin Białoń <mbialon@spacelift.io>
This commit is contained in:
Marcin Białoń 2023-08-30 15:00:24 +02:00 committed by GitHub
parent 554f303899
commit aeac8968fc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 154 additions and 178 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
website/docs/language/state/backends.mdx
View File

@ -1,17 +1,17 @@
---
page_title: 'Backends: State Storage and Locking'
description: >-
Backends are configured directly in Terraform files in the `terraform`
Backends are configured directly in OpenTF files in the `terraform`
section.
---
# State Storage and Locking
Backends are responsible for storing state and providing an API for
[state locking](/terraform/language/state/locking). State locking is optional.
[state locking](/opentf/language/state/locking). State locking is optional.
Despite the state being stored remotely, all Terraform commands such
as `terraform console`, the `terraform state` operations, `terraform taint`,
Despite the state being stored remotely, all OpenTF commands such
as `opentf console`, the `opentf state` operations, `opentf taint`,
and more will continue to work as if the state was local.
## State Storage
@ -21,13 +21,13 @@ backend stores state in a local JSON file on disk. The Consul backend stores
the state within Consul. Both of these backends happen to provide locking:
local via system APIs and Consul via locking APIs.
When using a non-local backend, Terraform will not persist the state anywhere
When using a non-local backend, OpenTF will not persist the state anywhere
on disk except in the case of a non-recoverable error where writing the state
to the backend failed. This behavior is a major benefit for backends: if
sensitive values are in your state, using a remote backend allows you to use
Terraform without that state ever being persisted to disk.
OpenTF without that state ever being persisted to disk.
In the case of an error persisting the state to the backend, Terraform will
In the case of an error persisting the state to the backend, OpenTF will
write the state locally. This is to prevent data loss. If this happens, the
end user must manually push the state to the remote backend once the error
is resolved.
@ -35,38 +35,38 @@ is resolved.
## Manual State Pull/Push
You can still manually retrieve the state from the remote state using
the `terraform state pull` command. This will load your remote state and
the `opentf state pull` command. This will load your remote state and
output it to stdout. You can choose to save that to a file or perform any
other operations.
You can also manually write state with `terraform state push`. **This
You can also manually write state with `opentf state push`. **This
is extremely dangerous and should be avoided if possible.** This will
overwrite the remote state. This can be used to do manual fixups if necessary.
When manually pushing state, Terraform will attempt to protect you from
When manually pushing state, OpenTF will attempt to protect you from
some potentially dangerous situations:
- **Differing lineage**: The "lineage" is a unique ID assigned to a state
when it is created. If a lineage is different, then it means the states
were created at different times and its very likely you're modifying a
different state. Terraform will not allow this.
different state. OpenTF will not allow this.
- **Higher serial**: Every state has a monotonically increasing "serial"
number. If the destination state has a higher serial, Terraform will
number. If the destination state has a higher serial, OpenTF will
not allow you to write it since it means that changes have occurred since
the state you're attempting to write.
Both of these protections can be bypassed with the `-force` flag if you're
confident you're making the right decision. Even if using the `-force` flag,
we recommend making a backup of the state with `terraform state pull`
we recommend making a backup of the state with `opentf state pull`
prior to forcing the overwrite.
## State Locking
Backends are responsible for supporting [state locking](/terraform/language/state/locking)
Backends are responsible for supporting [state locking](/opentf/language/state/locking)
if possible.
Not all backends support locking. The [documentation for each backend](/terraform/language/settings/backends/configuration#available-backends) includes details about whether it supports locking or not.
Not all backends support locking. The [documentation for each backend](/opentf/language/settings/backends/configuration#available-backends) includes details about whether it supports locking or not.
For more information on state locking, view the
[page dedicated to state locking](/terraform/language/state/locking).
[page dedicated to state locking](/opentf/language/state/locking).

10
website/docs/language/state/import.mdx
View File

@ -1,13 +1,13 @@
---
page_title: 'State: Import Existing Resources'
description: >-
Terraform stores state which caches the known state of the world the last time
Terraform ran.
OpenTF stores state which caches the known state of the world the last time
OpenTF ran.
---
# Import Existing Resources
Terraform is able to import existing infrastructure. This allows you to take
resources you have created by some other means and bring them under Terraform management.
OpenTF is able to import existing infrastructure. This allows you to take
resources you have created by some other means and bring them under OpenTF management.
To learn more, see [Import](/terraform/language/import).
To learn more, see [Import](/opentf/language/import).

52
website/docs/language/state/index.mdx
View File

@ -1,66 +1,66 @@
---
page_title: State
description: >-
An introduction to state, information that Terraform uses to map resources to
An introduction to state, information that OpenTF uses to map resources to
a configuration, track metadata, and improve performance.
---
# State
Terraform must store state about your managed infrastructure and
configuration. This state is used by Terraform to map real world
OpenTF must store state about your managed infrastructure and
configuration. This state is used by OpenTF to map real world
resources to your configuration, keep track of metadata, and to improve
performance for large infrastructures.
This state is stored by default in a local file named "terraform.tfstate",
but we recommend [storing it in Terraform Cloud](/terraform/cloud-docs/migrate)
but we recommend storing it in TACOS (TF Automation and Collaboration Software)
to version, encrypt, and securely share it with your team.
Terraform uses state to determine which changes to make to your
infrastructure. Prior to any operation, Terraform does a
[refresh](/terraform/cli/commands/refresh) to update the state with the
OpenTF uses state to determine which changes to make to your
infrastructure. Prior to any operation, OpenTF does a
[refresh](/opentf/cli/commands/refresh) to update the state with the
real infrastructure.
The primary purpose of Terraform state is to store bindings between objects in
The primary purpose of OpenTF state is to store bindings between objects in
a remote system and resource instances declared in your configuration.
When Terraform creates a remote object in response to a change of configuration,
When OpenTF creates a remote object in response to a change of configuration,
it will record the identity of that remote object against a particular
resource instance, and then potentially update or delete that object in
response to future configuration changes.
For more information on why Terraform requires state and why Terraform cannot
function without state, please see the page [state purpose](/terraform/language/state/purpose).
For more information on why OpenTF requires state and why OpenTF cannot
function without state, please see the page [state purpose](/opentf/language/state/purpose).
## Inspection and Modification
While the format of the state files are just JSON, direct file editing
of the state is discouraged. Terraform provides the
[terraform state](/terraform/cli/commands/state) command to perform
of the state is discouraged. OpenTF provides the
[opentf state](/opentf/cli/commands/state) command to perform
basic modifications of the state using the CLI.
The CLI usage and output of the state commands is structured to be
friendly for Unix tools such as grep, awk, etc. Additionally, the CLI
insulates users from any format changes within the state itself. The Terraform
insulates users from any format changes within the state itself. The OpenTF
project will keep the CLI working while the state format underneath it may
shift.
Terraform expects a one-to-one mapping between configured resource instances
and remote objects. Normally that is guaranteed by Terraform being the one
OpenTF expects a one-to-one mapping between configured resource instances
and remote objects. Normally that is guaranteed by OpenTF being the one
to create each object and record its identity in the state, or to destroy
an object and then remove the binding for it.
If you add or remove bindings in the state by other means, such as by importing
externally-created objects with `terraform import`, or by asking Terraform to
"forget" an existing object with `terraform state rm`, you'll then need to
externally-created objects with `opentf import`, or by asking OpenTF to
"forget" an existing object with `opentf state rm`, you'll then need to
ensure for yourself that this one-to-one rule is followed, such as by manually
deleting an object that you asked Terraform to "forget", or by re-importing it
deleting an object that you asked OpenTF to "forget", or by re-importing it
to bind it to some other resource instance.
## Format
State snapshots are stored in JSON format and new Terraform versions are
State snapshots are stored in JSON format and new OpenTF versions are
generally backward compatible with state snapshots produced by earlier versions.
However, the state format is subject to change in new Terraform versions, so
However, the state format is subject to change in new OpenTF versions, so
if you build software that parses or modifies it directly you should expect
to perform ongoing maintenance of that software as the state format evolves
in new versions.
@ -68,16 +68,16 @@ in new versions.
Alternatively, there are several integration points which produce JSON output
that is specifically intended for consumption by external software:
* [The `terraform output` command](/terraform/cli/commands/output)
* [The `opentf output` command](/opentf/cli/commands/output)
has a `-json` option, for obtaining either the full set of root module output
values or a specific named output value from the latest state snapshot.
* [The `terraform show` command](/terraform/cli/commands/show) has a `-json`
* [The `opentf show` command](/opentf/cli/commands/show) has a `-json`
option for inspecting the latest state snapshot in full, and also for
inspecting saved plan files which include a copy of the prior state at the
time the plan was made.
A typical way to use these in situations where Terraform is running in
automation is to run them immediately after a successful `terraform apply`
A typical way to use these in situations where OpenTF is running in
automation is to run them immediately after a successful `opentf apply`
to obtain a representation of the latest state snapshot, and then store that
result as an artifact associated with the automated run so that other software
can potentially consume it without needing to run Terraform itself.
can potentially consume it without needing to run OpenTF itself.

18
website/docs/language/state/locking.mdx
View File

@ -1,32 +1,32 @@
---
page_title: 'State: Locking'
description: >-
Terraform stores state which caches the known state of the world the last time
Terraform ran.
OpenTF stores state which caches the known state of the world the last time
OpenTF ran.
---
# State Locking
If supported by your [backend](/terraform/language/settings/backends/configuration), Terraform will lock your
If supported by your [backend](/opentf/language/settings/backends/configuration), OpenTF will lock your
state for all operations that could write state. This prevents
others from acquiring the lock and potentially corrupting your state.
State locking happens automatically on all operations that could write
state. You won't see any message that it is happening. If state locking fails,
Terraform will not continue. You can disable state locking for most commands
OpenTF will not continue. You can disable state locking for most commands
with the `-lock` flag but it is not recommended.
If acquiring the lock is taking longer than expected, Terraform will output
a status message. If Terraform doesn't output a message, state locking is
If acquiring the lock is taking longer than expected, OpenTF will output
a status message. If OpenTF doesn't output a message, state locking is
still occurring if your backend supports it.
Not all backends support locking. The
[documentation for each backend](/terraform/language/settings/backends/configuration)
[documentation for each backend](/opentf/language/settings/backends/configuration)
includes details on whether it supports locking or not.
## Force Unlock
Terraform has a [force-unlock command](/terraform/cli/commands/force-unlock)
OpenTF has a [force-unlock command](/opentf/cli/commands/force-unlock)
to manually unlock the state if unlocking failed.
**Be very careful with this command.** If you unlock the state when someone
@ -34,7 +34,7 @@ else is holding the lock it could cause multiple writers. Force unlock should
only be used to unlock your own lock in the situation where automatic
unlocking failed.
To protect you, the `force-unlock` command requires a unique lock ID. Terraform
To protect you, the `force-unlock` command requires a unique lock ID. OpenTF
will output this lock ID if unlocking fails. This lock ID acts as a
[nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce), ensuring
that locks and unlocks target the correct lock.

78
website/docs/language/state/purpose.mdx
View File

@ -1,109 +1,109 @@
---
page_title: State
description: >-
Terraform must store state about your managed infrastructure and
configuration. This state is used by Terraform to map real world resources to
OpenTF must store state about your managed infrastructure and
configuration. This state is used by OpenTF to map real world resources to
your configuration, keep track of metadata, and to improve performance for
large infrastructures.
---
# Purpose of Terraform State
# Purpose of OpenTF State
State is a necessary requirement for Terraform to function. It is often
asked if it is possible for Terraform to work without state, or for Terraform
State is a necessary requirement for OpenTF to function. It is often
asked if it is possible for OpenTF to work without state, or for OpenTF
to not use state and just inspect real world resources on every run. This page
will help explain why Terraform state is required.
will help explain why OpenTF state is required.
As you'll see from the reasons below, state is required. And in the scenarios
where Terraform may be able to get away without state, doing so would require
where OpenTF may be able to get away without state, doing so would require
shifting massive amounts of complexity from one place (state) to another place
(the replacement concept).
## Mapping to the Real World
Terraform requires some sort of database to map Terraform config to the real
OpenTF requires some sort of database to map OpenTF config to the real
world. For example, when you have a resource `resource "aws_instance" "foo"` in your
configuration, Terraform uses this mapping to know that the resource `resource "aws_instance" "foo"`
configuration, OpenTF uses this mapping to know that the resource `resource "aws_instance" "foo"`
represents a real world object with the instance ID `i-abcd1234` on a remote system.
For some providers like AWS, Terraform could theoretically use something like
AWS tags. Early prototypes of Terraform actually had no state files and used
For some providers like AWS, OpenTF could theoretically use something like
AWS tags. Early prototypes of OpenTF actually had no state files and used
this method. However, we quickly ran into problems. The first major issue was
a simple one: not all resources support tags, and not all cloud providers
support tags.
Therefore, for mapping configuration to resources in the real world,
Terraform uses its own state structure.
OpenTF uses its own state structure.
Terraform expects that each remote object is bound to only one resource instance in the configuration.
OpenTF expects that each remote object is bound to only one resource instance in the configuration.
If a remote object is bound to multiple resource instances, the mapping from configuration to the remote
object in the state becomes ambiguous, and Terraform may behave unexpectedly. Terraform can guarantee
object in the state becomes ambiguous, and OpenTF may behave unexpectedly. OpenTF can guarantee
a one-to-one mapping when it creates objects and records their identities in the state.
When importing objects created outside of Terraform, you must make sure that each distinct object
When importing objects created outside of OpenTF, you must make sure that each distinct object
is imported to only one resource instance.
## Metadata
Alongside the mappings between resources and remote objects, Terraform must
Alongside the mappings between resources and remote objects, OpenTF must
also track metadata such as resource dependencies.
Terraform typically uses the configuration to determine dependency order.
However, when you delete a resource from a Terraform configuration, Terraform
must know how to delete that resource from the remote system. Terraform can see that a mapping exists
OpenTF typically uses the configuration to determine dependency order.
However, when you delete a resource from an OpenTF configuration, OpenTF
must know how to delete that resource from the remote system. OpenTF can see that a mapping exists
in the state file for a resource not in your configuration and plan to destroy. However, since
the configuration no longer exists, the order cannot be determined from the
configuration alone.
To ensure correct operation, Terraform retains a copy of the most recent set
of dependencies within the state. Now Terraform can still determine the correct
To ensure correct operation, OpenTF retains a copy of the most recent set
of dependencies within the state. Now OpenTF can still determine the correct
order for destruction from the state when you delete one or more items from
the configuration.
One way to avoid this would be for Terraform to know a required ordering
between resource types. For example, Terraform could know that servers must be
One way to avoid this would be for OpenTF to know a required ordering
between resource types. For example, OpenTF could know that servers must be
deleted before the subnets they are a part of. The complexity for this approach
quickly explodes, however: in addition to Terraform having to understand the
ordering semantics of every resource for every _provider_, Terraform must also
quickly explodes, however: in addition to OpenTF having to understand the
ordering semantics of every resource for every _provider_, OpenTF must also
understand the ordering _across providers_.
Terraform also stores other metadata for similar reasons, such as a pointer
OpenTF also stores other metadata for similar reasons, such as a pointer
to the provider configuration that was most recently used with the resource
in situations where multiple aliased providers are present.
## Performance
In addition to basic mapping, Terraform stores a cache of the attribute
In addition to basic mapping, OpenTF stores a cache of the attribute
values for all resources in the state. This is the most optional feature of
Terraform state and is done only as a performance improvement.
OpenTF state and is done only as a performance improvement.
When running a `terraform plan`, Terraform must know the current state of
When running a `opentf plan`, OpenTF must know the current state of
resources in order to effectively determine the changes that it needs to make
to reach your desired configuration.
For small infrastructures, Terraform can query your providers and sync the
For small infrastructures, OpenTF can query your providers and sync the
latest attributes from all your resources. This is the default behavior
of Terraform: for every plan and apply, Terraform will sync all resources in
of OpenTF: for every plan and apply, OpenTF will sync all resources in
your state.
For larger infrastructures, querying every resource is too slow. Many cloud
providers do not provide APIs to query multiple resources at once, and the
round trip time for each resource is hundreds of milliseconds. On top of this,
cloud providers almost always have API rate limiting so Terraform can only
cloud providers almost always have API rate limiting so OpenTF can only
request a certain number of resources in a period of time. Larger users
of Terraform make heavy use of the `-refresh=false` flag as well as the
of OpenTF make heavy use of the `-refresh=false` flag as well as the
`-target` flag in order to work around this. In these scenarios, the cached
state is treated as the record of truth.
## Syncing
In the default configuration, Terraform stores the state in a file in the
current working directory where Terraform was run. This is okay for getting
started, but when using Terraform in a team it is important for everyone
In the default configuration, OpenTF stores the state in a file in the
current working directory where OpenTF was run. This is okay for getting
started, but when using OpenTF in a team it is important for everyone
to be working with the same state so that operations will be applied to the
same remote objects.
[Remote state](/terraform/language/state/remote) is the recommended solution
to this problem. With a fully-featured state backend, Terraform can use
[Remote state](/opentf/language/state/remote) is the recommended solution
to this problem. With a fully-featured state backend, OpenTF can use
remote locking as a measure to avoid two or more different users accidentally
running Terraform at the same time, and thus ensure that each Terraform run
running OpenTF at the same time, and thus ensure that each OpenTF run
begins with the most recent updated state.

47
website/docs/language/state/remote-state-data.mdx
View File

@ -1,18 +1,18 @@
---
page_title: The terraform_remote_state Data Source
description: >-
Retrieves the root module output values from a Terraform state snapshot stored
Retrieves the root module output values from an OpenTF state snapshot stored
in a remote backend.
---
# The `terraform_remote_state` Data Source
[backends]: /terraform/language/settings/backends/configuration
[backends]: /opentf/language/settings/backends/configuration
The `terraform_remote_state` data source uses the latest state snapshot from a specified state backend to retrieve the root module output values
from some other Terraform configuration.
from some other OpenTF configuration.
You can use the `terraform_remote_state` data source without requiring or configuring a provider. It is always available through a built-in provider with the [source address](/terraform/language/providers/requirements#source-addresses) `terraform.io/builtin/terraform`. That provider does not include any other resources or data sources.
You can use the `terraform_remote_state` data source without requiring or configuring a provider. It is always available through a built-in provider with the [source address](/opentf/language/providers/requirements#source-addresses) `terraform.io/builtin/terraform`. That provider does not include any other resources or data sources.
## Alternative Ways to Share Data Between Configurations
@ -44,16 +44,16 @@ limited to) the following:
| Kubernetes | [`kubernetes_config_map` resource type](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/config_map) | [`kubernetes_config_map` data source](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/data-sources/config_map) |
| OCI Object Storage | [`oci_objectstorage_bucket` resource type](https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/objectstorage_object) | [`oci_objectstorage_bucket` data source](https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/objectstorage_object) |
-> These are some common options from the Official Terraform providers, but
-> These are some common options from the Official OpenTF providers, but
there are too many configuration storage options for us to list them all
here, including some in partner and community providers.
Any pair of managed resource type and corresponding data source can potentially
be used to share data between Terraform configurations. See individual provider
be used to share data between OpenTF configurations. See individual provider
documentation to find other possibilities.
A key advantage of using a separate explicit configuration store instead of
`terraform_remote_state` is that the data can potentially also be read by
systems other than Terraform, such as configuration management or scheduler
systems other than OpenTF, such as configuration management or scheduler
systems within your compute instances. For that reason, we recommend selecting
a configuration store that your other infrastructure could potentially make
use of. For example:
@ -74,18 +74,18 @@ use of. For example:
Some of the data stores listed above are specifically designed for storing
small configuration values, while others are generic blob storage systems. For
those generic systems, you can use
[the `jsonencode` function](/terraform/language/functions/jsonencode)
[the `jsonencode` function](/opentf/language/functions/jsonencode)
and
[the `jsondecode` function](/terraform/language/functions/jsondecode) respectively
[the `jsondecode` function](/opentf/language/functions/jsondecode) respectively
to store and retrieve structured data.
You can encapsulate the implementation details of retrieving your published
configuration data by writing a
[data-only module](/terraform/language/modules/develop/composition#data-only-modules)
[data-only module](/opentf/language/modules/develop/composition#data-only-modules)
containing the necessary data source configuration and any necessary
post-processing such as JSON decoding. You can then change that module later
if you switch to a different strategy for sharing data between multiple
Terraform configurations.
OpenTF configurations.
## Example Usage (`remote` Backend)
@ -101,17 +101,10 @@ data "terraform_remote_state" "vpc" {
}
}
# Terraform >= 0.12
resource "aws_instance" "foo" {
# ...
subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id
}
# Terraform <= 0.11
resource "aws_instance" "foo" {
# ...
subnet_id = "${data.terraform_remote_state.vpc.subnet_id}"
}
```
## Example Usage (`local` Backend)
@ -125,17 +118,10 @@ data "terraform_remote_state" "vpc" {
}
}
# Terraform >= 0.12
resource "aws_instance" "foo" {
# ...
subnet_id = data.terraform_remote_state.vpc.outputs.subnet_id
}
# Terraform <= 0.11
resource "aws_instance" "foo" {
# ...
subnet_id = "${data.terraform_remote_state.vpc.subnet_id}"
}
```
## Argument Reference
@ -143,7 +129,7 @@ resource "aws_instance" "foo" {
The following arguments are supported:
* `backend` - (Required) The remote backend to use.
* `workspace` - (Optional) The Terraform workspace to use, if the backend
* `workspace` - (Optional) The OpenTF workspace to use, if the backend
supports workspaces.
* `config` - (Optional; object) The configuration of the remote backend.
Although this argument is listed as optional, most backends require
@ -151,7 +137,7 @@ The following arguments are supported:
The `config` object can use any arguments that would be valid in the
equivalent `terraform { backend "<TYPE>" { ... } }` block. See
[the documentation of your chosen backend](/terraform/language/settings/backends/configuration)
[the documentation of your chosen backend](/opentf/language/settings/backends/configuration)
for details.
-> **Note:** If the backend configuration requires a nested block, specify
@ -164,10 +150,8 @@ The following arguments are supported:
In addition to the above, the following attributes are exported:
* (v0.12+) `outputs` - An object containing every root-level
[output](/terraform/language/values/outputs) in the remote state.
* (<= v0.11) `<OUTPUT NAME>` - Each root-level [output](/terraform/language/values/outputs)
in the remote state appears as a top level attribute on the data source.
* `outputs` - An object containing every root-level
[output](/opentf/language/values/outputs) in the remote state.
## Root Outputs Only
@ -187,7 +171,6 @@ module "app" {
}
output "app_value" {
# This syntax is for Terraform 0.12 or later.
value = module.app.example
}
```

40
website/docs/language/state/remote.mdx
View File

@ -1,30 +1,30 @@
---
page_title: 'State: Remote Storage'
description: >-
Terraform can store the state remotely, making it easier to version and work
OpenTF can store the state remotely, making it easier to version and work
with in a team.
---
# Remote State
By default, Terraform stores state locally in a file named `terraform.tfstate`.
When working with Terraform in a team, use of a local file makes Terraform
By default, OpenTF stores state locally in a file named `terraform.tfstate`.
When working with OpenTF in a team, use of a local file makes OpenTF
usage complicated because each user must make sure they always have the latest
state data before running Terraform and make sure that nobody else runs
Terraform at the same time.
state data before running OpenTF and make sure that nobody else runs
OpenTF at the same time.
With _remote_ state, Terraform writes the state data to a remote data store,
which can then be shared between all members of a team. Terraform supports
storing state in [Terraform Cloud](https://www.hashicorp.com/products/terraform/),
With _remote_ state, OpenTF writes the state data to a remote data store,
which can then be shared between all members of a team. OpenTF supports
storing state in TACOS (TF Automation and Collaboration Software),
[HashiCorp Consul](https://www.consul.io/), Amazon S3, Azure Blob Storage, Google Cloud Storage, Alibaba Cloud OSS, and more.
Remote state is implemented by a [backend](/terraform/language/settings/backends/configuration) or by
Terraform Cloud, both of which you can configure in your configuration's root module.
Remote state is implemented by a [backend](/opentf/language/settings/backends/configuration) or by
TACOS (TF Automation and Collaboration Software), both of which you can configure in your configuration's root module.
## Delegation and Teamwork
Remote state allows you to share
[output values](/terraform/language/values/outputs) with other configurations.
[output values](/opentf/language/values/outputs) with other configurations.
This allows your infrastructure to be decomposed into smaller components.
Put another way, remote state also allows teams to share infrastructure
@ -35,29 +35,29 @@ For example, a core infrastructure team can handle building the core
machines, networking, etc. and can expose some information to other
teams to run their own infrastructure. As a more specific example with AWS:
you can expose things such as VPC IDs, subnets, NAT instance IDs, etc. through
remote state and have other Terraform states consume that.
remote state and have other OpenTF states consume that.
For example usage, see
[the `terraform_remote_state` data source](/terraform/language/state/remote-state-data).
[the `terraform_remote_state` data source](/opentf/language/state/remote-state-data).
While remote state can be a convenient, built-in mechanism for sharing data
between configurations, you may prefer to use more general stores to
pass settings both to other configurations and to other consumers. For example,
if your environment has [HashiCorp Consul](https://www.consul.io/) then you
can have one Terraform configuration that writes to Consul using
can have one OpenTF configuration that writes to Consul using
[`consul_key_prefix`](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/resources/key_prefix) and then
another that consumes those values using
[the `consul_keys` data source](https://registry.terraform.io/providers/hashicorp/consul/latest/docs/data-sources/keys).
## Locking and Teamwork
For fully-featured remote backends, Terraform can also use
[state locking](/terraform/language/state/locking) to prevent concurrent runs of
Terraform against the same state.
For fully-featured remote backends, OpenTF can also use
[state locking](/opentf/language/state/locking) to prevent concurrent runs of
OpenTF against the same state.
[Terraform Cloud by HashiCorp](https://www.hashicorp.com/products/terraform/)
is a commercial offering that supports an even stronger locking concept that
TACOS (TF Automation and Collaboration Software) is a commercial offering
that supports an even stronger locking concept that
can also detect attempts to create a new plan when an existing plan is already
awaiting approval, by queuing Terraform operations in a central location.
awaiting approval, by queuing OpenTF operations in a central location.
This allows teams to more easily coordinate and communicate about changes to
infrastructure.

19
website/docs/language/state/sensitive-data.mdx
View File

@ -1,37 +1,32 @@
---
page_title: 'State: Sensitive Data'
description: Sensitive data in Terraform state.
description: Sensitive data in OpenTF state.
---
# Sensitive Data in State
Terraform state can contain sensitive data, depending on the resources in use
OpenTF state can contain sensitive data, depending on the resources in use
and your definition of "sensitive." The state contains resource IDs and all
resource attributes. For resources such as databases, this may contain initial
passwords.
When using local state, state is stored in plain-text JSON files.
When using [remote state](/terraform/language/state/remote), state is only ever held in
memory when used by Terraform. It may be encrypted at rest, but this depends on
When using [remote state](/opentf/language/state/remote), state is only ever held in
memory when used by OpenTF. It may be encrypted at rest, but this depends on
the specific remote state backend.
## Recommendations
If you manage any sensitive data with Terraform (like database passwords, user
If you manage any sensitive data with OpenTF (like database passwords, user
passwords, or private keys), treat the state itself as sensitive data.
Storing state remotely can provide better security. As of Terraform 0.9,
Terraform does not persist state to the local disk when remote state is in use,
Storing state remotely can provide better security.
OpenTF does not persist state to the local disk when remote state is in use,
and some backends can be configured to encrypt the state data at rest.
For example:
- [Terraform Cloud](https://cloud.hashicorp.com/products/terraform) always encrypts state at rest and
protects it with TLS in transit. Terraform Cloud also knows the identity of
the user requesting state and maintains a history of state changes. This can
be used to control access and track activity. [Terraform Enterprise](/terraform/enterprise)
also supports detailed audit logging.
- The S3 backend supports encryption at rest when the `encrypt` option is
enabled. IAM policies and logging can be used to identify any invalid access.
Requests for the state go over a TLS connection.

36
website/docs/language/state/workspaces.mdx
View File

@ -7,43 +7,41 @@ description: >-
# Workspaces
Each Terraform configuration has an associated [backend](/terraform/language/settings/backends/configuration) that defines how Terraform executes operations and where Terraform stores persistent data, like [state](/terraform/language/state/purpose).
Each OpenTF configuration has an associated [backend](/opentf/language/settings/backends/configuration) that defines how OpenTF executes operations and where OpenTF stores persistent data, like [state](/opentf/language/state/purpose).
The persistent data stored in the backend belongs to a workspace. The backend initially has only one workspace containing one Terraform state associated with that configuration. Some backends support multiple named workspaces, allowing multiple states to be associated with a single configuration. The configuration still has only one backend, but you can deploy multiple distinct instances of that configuration without configuring a new backend or changing authentication
The persistent data stored in the backend belongs to a workspace. The backend initially has only one workspace containing one OpenTF state associated with that configuration. Some backends support multiple named workspaces, allowing multiple states to be associated with a single configuration. The configuration still has only one backend, but you can deploy multiple distinct instances of that configuration without configuring a new backend or changing authentication
credentials.
-> **Note**: The Terraform CLI workspaces are different from [workspaces in Terraform Cloud](/terraform/cloud-docs/workspaces). Refer to [Initializing and Migrating](/terraform/cli/cloud/migrating) for details about migrating a configuration with multiple workspaces to Terraform Cloud.
## Backends Supporting Multiple Workspaces
You can use multiple workspaces with the following backends:
- [AzureRM](/terraform/language/settings/backends/azurerm)
- [Consul](/terraform/language/settings/backends/consul)
- [COS](/terraform/language/settings/backends/cos)
- [GCS](/terraform/language/settings/backends/gcs)
- [Kubernetes](/terraform/language/settings/backends/kubernetes)
- [Local](/terraform/language/settings/backends/local)
- [OSS](/terraform/language/settings/backends/oss)
- [Postgres](/terraform/language/settings/backends/pg)
- [Remote](/terraform/language/settings/backends/remote)
- [S3](/terraform/language/settings/backends/s3)
- [AzureRM](/opentf/language/settings/backends/azurerm)
- [Consul](/opentf/language/settings/backends/consul)
- [COS](/opentf/language/settings/backends/cos)
- [GCS](/opentf/language/settings/backends/gcs)
- [Kubernetes](/opentf/language/settings/backends/kubernetes)
- [Local](/opentf/language/settings/backends/local)
- [OSS](/opentf/language/settings/backends/oss)
- [Postgres](/opentf/language/settings/backends/pg)
- [Remote](/opentf/language/settings/backends/remote)
- [S3](/opentf/language/settings/backends/s3)
## Using Workspaces
~> **Important:** Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [Use Cases](/terraform/cli/workspaces#use-cases) in the Terraform CLI documentation for details and recommended alternatives.
~> **Important:** Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [Use Cases](/opentf/cli/workspaces#use-cases) in the OpenTF CLI documentation for details and recommended alternatives.
Terraform starts with a single, default workspace named `default` that you cannot delete. If you have not created a new workspace, you are using the default workspace in your Terraform working directory.
OpenTF starts with a single, default workspace named `default` that you cannot delete. If you have not created a new workspace, you are using the default workspace in your OpenTF working directory.
When you run `terraform plan` in a new workspace, Terraform does not access existing resources in other workspaces. These resources still physically exist, but you must switch workspaces to manage them.
When you run `opentf plan` in a new workspace, OpenTF does not access existing resources in other workspaces. These resources still physically exist, but you must switch workspaces to manage them.
Refer to the [Terraform CLI workspaces](/terraform/cli/workspaces) documentation for full details about how to create and use workspaces.
Refer to the [OpenTF CLI workspaces](/opentf/cli/workspaces) documentation for full details about how to create and use workspaces.
## Current Workspace Interpolation
Within your Terraform configuration, you may include the name of the current
Within your OpenTF configuration, you may include the name of the current
workspace using the `${terraform.workspace}` interpolation sequence. This can
be used anywhere interpolations are allowed.