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/settings (#233)

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

36
website/docs/language/settings/backends/azurerm.mdx
View File

@ -1,6 +1,6 @@
---
page_title: 'Backend Type: azurerm'
description: Terraform can store state remotely in Azure Blob Storage.
description: OpenTF can store state remotely in Azure Blob Storage.
---
# azurerm
@ -9,8 +9,6 @@ Stores the state as a Blob with the given Key within the Blob Container within [
This backend supports state locking and consistency checking with Azure Blob Storage native capabilities.
~> **Terraform 1.1 and 1.2 supported a feature-flag to allow enabling/disabling the use of Microsoft Graph (and MSAL) rather than Azure Active Directory Graph (and ADAL) - however this flag has since been removed in Terraform 1.3. Microsoft Graph (and MSAL) are now enabled by default and Azure Active Directory Graph (and ADAL) can no longer be used.
## Example Configuration
When authenticating using the Azure CLI or a Service Principal (either with a Client Certificate or a Client Secret):
@ -117,7 +115,7 @@ terraform {
}
```
-> **NOTE:** When using a Service Principal or an Access Key - we recommend using a [Partial Configuration](/terraform/language/settings/backends/configuration#partial-configuration) for the credentials.
-> **NOTE:** When using a Service Principal or an Access Key - we recommend using a [Partial Configuration](/opentf/language/settings/backends/configuration#partial-configuration) for the credentials.
## Data Source Configuration
@ -127,8 +125,8 @@ When authenticating using a Service Principal (either with a Client Certificate
data "terraform_remote_state" "foo" {
backend = "azurerm"
config = {
storage_account_name = "terraform123abc"
container_name = "terraform-state"
storage_account_name = "opentf123abc"
container_name = "opentf-state"
key = "prod.terraform.tfstate"
}
}
@ -143,8 +141,8 @@ data "terraform_remote_state" "foo" {
backend = "azurerm"
config = {
resource_group_name = "StorageAccount-ResourceGroup"
storage_account_name = "terraform123abc"
container_name = "terraform-state"
storage_account_name = "opentf123abc"
container_name = "opentf-state"
key = "prod.terraform.tfstate"
use_msi = true
subscription_id = "00000000-0000-0000-0000-000000000000"
@ -162,8 +160,8 @@ data "terraform_remote_state" "foo" {
backend = "azurerm"
config = {
resource_group_name = "StorageAccount-ResourceGroup"
storage_account_name = "terraform123abc"
container_name = "terraform-state"
storage_account_name = "opentf123abc"
container_name = "opentf-state"
key = "prod.terraform.tfstate"
use_oidc = true
subscription_id = "00000000-0000-0000-0000-000000000000"
@ -180,8 +178,8 @@ When authenticating using AzureAD Authentication:
data "terraform_remote_state" "foo" {
backend = "azurerm"
config = {
storage_account_name = "terraform123abc"
container_name = "terraform-state"
storage_account_name = "opentf123abc"
container_name = "opentf-state"
key = "prod.terraform.tfstate"
use_azuread_auth = true
subscription_id = "00000000-0000-0000-0000-000000000000"
@ -200,8 +198,8 @@ When authenticating using the Access Key associated with the Storage Account:
data "terraform_remote_state" "foo" {
backend = "azurerm"
config = {
storage_account_name = "terraform123abc"
container_name = "terraform-state"
storage_account_name = "opentf123abc"
container_name = "opentf-state"
key = "prod.terraform.tfstate"
# rather than defining this inline, the Access Key can also be sourced
@ -219,8 +217,8 @@ When authenticating using a SAS Token associated with the Storage Account:
data "terraform_remote_state" "foo" {
backend = "azurerm"
config = {
storage_account_name = "terraform123abc"
container_name = "terraform-state"
storage_account_name = "opentf123abc"
container_name = "opentf-state"
key = "prod.terraform.tfstate"
# rather than defining this inline, the SAS Token can also be sourced
@ -232,7 +230,7 @@ data "terraform_remote_state" "foo" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
The following configuration options are supported:
@ -241,7 +239,7 @@ The following configuration options are supported:
* `container_name` - (Required) The Name of [the Storage Container](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/storage_container) within the Storage Account.
* `key` - (Required) The name of the Blob used to retrieve/store Terraform's State file inside the Storage Container.
* `key` - (Required) The name of the Blob used to retrieve/store OpenTF's State file inside the Storage Container.
* `environment` - (Optional) The Azure Environment which should be used. This can also be sourced from the `ARM_ENVIRONMENT` environment variable. Possible values are `public`, `china`, `german`, `stack` and `usgovernment`. Defaults to `public`.
@ -251,7 +249,7 @@ The following configuration options are supported:
* `metadata_host` - (Optional) The Hostname of the Azure Metadata Service (for example `management.azure.com`), used to obtain the Cloud Environment when using a Custom Azure Environment. This can also be sourced from the `ARM_METADATA_HOSTNAME` Environment Variable.
* `snapshot` - (Optional) Should the Blob used to store the Terraform Statefile be snapshotted before use? Defaults to `false`. This value can also be sourced from the `ARM_SNAPSHOT` environment variable.
* `snapshot` - (Optional) Should the Blob used to store the OpenTF Statefile be snapshotted before use? Defaults to `false`. This value can also be sourced from the `ARM_SNAPSHOT` environment variable.
***

84
website/docs/language/settings/backends/configuration.mdx
View File

@ -1,34 +1,30 @@
---
page_title: Backend Configuration - Configuration Language
description: >-
Use the `backend` block to control where Terraform stores state. Learn about the available state backends, the backend block, initializing backends, partial backend configuration, changing backend configuration, and unconfiguring a backend.
Use the `backend` block to control where OpenTF stores state. Learn about the available state backends, the backend block, initializing backends, partial backend configuration, changing backend configuration, and unconfiguring a backend.
---
# Backend Configuration
A backend defines where Terraform stores its [state](/terraform/language/state) data files.
A backend defines where OpenTF stores its [state](/opentf/language/state) data files.
Terraform uses persisted state data to keep track of the resources it manages. Most non-trivial Terraform configurations either [integrate with Terraform Cloud](/terraform/language/settings/tf-cloud) or use a backend to store state remotely. This lets multiple people access the state data and work together on that collection of infrastructure resources.
OpenTF uses persisted state data to keep track of the resources it manages. Most non-trivial OpenTF configurations either intergrate with TACOS (TF Automation and Collaboration Software) or use a backend to store state remotely. This lets multiple people access the state data and work together on that collection of infrastructure resources.
This page describes how to configure a backend by adding the [`backend` block](#using-a-backend-block) to your configuration.
-> **Note:** In Terraform versions before 1.1.0, we classified backends as standard or enhanced. The enhanced label differentiated the [`remote` backend](/terraform/language/settings/backends/remote), which could both store state and perform Terraform operations. This classification has been removed. Refer to [Using Terraform Cloud](/terraform/cli/cloud) for details about storing state, executing remote operations, and using Terraform Cloud directly from Terraform.
## Available Backends
By default, Terraform uses a backend called [`local`](/terraform/language/settings/backends/local), which stores state as a local file on disk. You can also configure one of the built-in backends included in this documentation.
By default, OpenTF uses a backend called [`local`](/opentf/language/settings/backends/local), which stores state as a local file on disk. You can also configure one of the built-in backends included in this documentation.
Some of these backends act like plain remote disks for state files, while others support locking the state while operations are being performed. This helps prevent conflicts and inconsistencies. The built-in backends listed are the only backends. You cannot load additional backends as plugins.
-> **Note:** We removed the `artifactory`, `etcd`, `etcdv3`, `manta`, and `swift` backends in Terraform v1.3. Information about their behavior in older versions is still available in the [Terraform v1.2 documentation](/terraform/language/v1.2.x/settings/backends/configuration). For migration paths from these removed backends, refer to [Upgrading to Terraform v1.3](/terraform/language/v1.3.x/upgrade-guides).
## Using a Backend Block
You do not need to configure a backend when using Terraform Cloud because
Terraform Cloud automatically manages state in the workspaces associated with your configuration. If your configuration includes a [`cloud` block](/terraform/language/settings/tf-cloud), it cannot include a `backend` block.
You do not need to configure a backend when using TACOS (TF Automation and Collaboration Software) because
it automatically manages state in the workspaces associated with your configuration. If your configuration includes a [`cloud` block](/opentf/language/settings/tf-cloud), it cannot include a `backend` block.
To configure a backend, add a nested `backend` block within the top-level
`terraform` block. The following example configures the `remote` backend.
`opentf` block. The following example configures the `remote` backend.
```hcl
terraform {
@ -51,17 +47,17 @@ There are some important limitations on backend configuration:
Backends store state in a remote service, which allows multiple people to access it. Accessing remote state generally requires access credentials, since state data contains extremely sensitive information.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. This can leak sensitive credentials.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. This can leak sensitive credentials.
Terraform writes the backend configuration in plain text in two separate files.
OpenTF writes the backend configuration in plain text in two separate files.
- The `.terraform/terraform.tfstate` file contains the backend configuration for the current working directory.
- All plan files capture the information in `.terraform/terraform.tfstate` at the time the plan was created. This helps ensure Terraform is applying the plan to correct set of infrastructure.
- All plan files capture the information in `.terraform/terraform.tfstate` at the time the plan was created. This helps ensure OpenTF is applying the plan to correct set of infrastructure.
When applying a plan that you previously saved to a file, Terraform uses the backend configuration stored in that file instead of the current backend settings. If that configuration contains time-limited credentials, they may expire before you finish applying the plan. Use environment variables to pass credentials when you need to use different values between the plan and apply steps.
When applying a plan that you previously saved to a file, OpenTF uses the backend configuration stored in that file instead of the current backend settings. If that configuration contains time-limited credentials, they may expire before you finish applying the plan. Use environment variables to pass credentials when you need to use different values between the plan and apply steps.
### Backend Types
The block label of the backend block (`"remote"`, in the example above) indicates which backend type to use. Terraform has a built-in selection of backends, and the configured backend must be available in the version of Terraform you are using.
The block label of the backend block (`"remote"`, in the example above) indicates which backend type to use. OpenTF has a built-in selection of backends, and the configured backend must be available in the version of OpenTF you are using.
The arguments used in the block's body are specific to the chosen backend type; they configure where and how the backend will store the configuration's state, and in some cases configure other behavior.
@ -71,19 +67,19 @@ Refer to the page for each backend type for full details and that type's configu
### Default Backend
If a configuration includes no backend block, Terraform defaults to using the `local` backend, which stores state as a plain file in the current working directory.
If a configuration includes no backend block, OpenTF defaults to using the `local` backend, which stores state as a plain file in the current working directory.
## Initialization
When you change a backend's configuration, you must run `terraform init` again
When you change a backend's configuration, you must run `opentf init` again
to validate and configure the backend before you can perform any plans, applies,
or state operations.
After you initialize, Terraform creates a `.terraform/` directory locally. This directory contains the most recent backend configuration, including any authentication parameters you provided to the Terraform CLI. Do not check this directory into Git, as it may contain sensitive credentials for your remote backend.
After you initialize, OpenTF creates a `.terraform/` directory locally. This directory contains the most recent backend configuration, including any authentication parameters you provided to the OpenTF CLI. Do not check this directory into Git, as it may contain sensitive credentials for your remote backend.
The local backend configuration is different and entirely separate from the `terraform.tfstate` file that contains [state data](/terraform/language/state) about your real-world infrastruture. Terraform stores the `terraform.tfstate` file in your remote backend.
The local backend configuration is different and entirely separate from the `terraform.tfstate` file that contains [state data](/opentf/language/state) about your real-world infrastruture. OpenTF stores the `terraform.tfstate` file in your remote backend.
When you change backends, Terraform gives you the option to migrate
When you change backends, OpenTF gives you the option to migrate
your state to the new backend. This lets you adopt backends without losing
any existing state.
@ -94,28 +90,28 @@ to another location.
You do not need to specify every required argument in the backend configuration.
Omitting certain arguments may be desirable if some arguments are provided
automatically by an automation script running Terraform. When some or all of
automatically by an automation script running OpenTF. When some or all of
the arguments are omitted, we call this a _partial configuration_.
With a partial configuration, the remaining configuration arguments must be
provided as part of [the initialization process](/terraform/cli/init).
provided as part of [the initialization process](/opentf/cli/init).
There are several ways to supply the remaining arguments:
- **File**: A configuration file may be specified via the `init` command line.
To specify a file, use the `-backend-config=PATH` option when running
`terraform init`. If the file contains secrets it may be kept in
`opentf init`. If the file contains secrets it may be kept in
a secure data store, such as [Vault](https://www.vaultproject.io/),
in which case it must be downloaded to the local disk before running Terraform.
in which case it must be downloaded to the local disk before running OpenTF.
- **Command-line key/value pairs**: Key/value pairs can be specified via the
`init` command line. Note that many shells retain command-line flags in a
history file, so this isn't recommended for secrets. To specify a single
key/value pair, use the `-backend-config="KEY=VALUE"` option when running
`terraform init`.
`opentf init`.
- **Interactively**: Terraform will interactively ask you for the required
values, unless interactive input is disabled. Terraform will not prompt for
- **Interactively**: OpenTF will interactively ask you for the required
values, unless interactive input is disabled. OpenTF will not prompt for
optional values.
If backend settings are provided in multiple locations, the top-level
@ -126,10 +122,10 @@ in order, with later options overriding values set by earlier options.
The final, merged configuration is stored on disk in the `.terraform`
directory, which should be ignored from version control. This means that
sensitive information can be omitted from version control, but it will be
present in plain text on local disk when running Terraform.
present in plain text on local disk when running OpenTF.
When using partial configuration, Terraform requires at a minimum that
an empty backend configuration is specified in one of the root Terraform
When using partial configuration, OpenTF requires at a minimum that
an empty backend configuration is specified in one of the root OpenTF
configuration files, to specify the backend type. For example:
```hcl
@ -141,7 +137,7 @@ terraform {
### File
A backend configuration file has the contents of the `backend` block as
top-level attributes, without the need to wrap it in another `terraform`
top-level attributes, without the need to wrap it in another `opentf`
or `backend` block:
```hcl
@ -151,7 +147,7 @@ scheme = "https"
```
`*.backendname.tfbackend` (e.g. `config.consul.tfbackend`) is the recommended
naming pattern. Terraform will not prevent you from using other names but following
naming pattern. OpenTF will not prevent you from using other names but following
this convention will help your editor understand the content and likely provide
better editing experience as a result.
@ -161,7 +157,7 @@ The same settings can alternatively be specified on the command line as
follows:
```
$ terraform init \
$ opentf init \
-backend-config="address=demo.consul.io" \
-backend-config="path=example_app/terraform_state" \
-backend-config="scheme=https"
@ -180,25 +176,25 @@ You can change your backend configuration at any time. You can change
both the configuration itself as well as the type of backend (for example
from "consul" to "s3").
Terraform will automatically detect any changes in your configuration
and request a [reinitialization](/terraform/cli/init). As part of
the reinitialization process, Terraform will ask if you'd like to migrate
OpenTF will automatically detect any changes in your configuration
and request a [reinitialization](/opentf/cli/init). As part of
the reinitialization process, OpenTF will ask if you'd like to migrate
your existing state to the new configuration. This allows you to easily
switch from one backend to another.
If you're using multiple [workspaces](/terraform/language/state/workspaces),
Terraform can copy all workspaces to the destination. If Terraform detects
If you're using multiple [workspaces](/opentf/language/state/workspaces),
OpenTF can copy all workspaces to the destination. If OpenTF detects
you have multiple workspaces, it will ask if this is what you want to do.
If you're just reconfiguring the same backend, Terraform will still ask if you
If you're just reconfiguring the same backend, OpenTF will still ask if you
want to migrate your state. You can respond "no" in this scenario.
## Unconfiguring a Backend
If you no longer want to use any backend, you can simply remove the
configuration from the file. Terraform will detect this like any other
change and prompt you to [reinitialize](/terraform/cli/init).
configuration from the file. OpenTF will detect this like any other
change and prompt you to [reinitialize](/opentf/cli/init).
As part of the reinitialization, Terraform will ask if you'd like to migrate
As part of the reinitialization, OpenTF will ask if you'd like to migrate
your state back down to normal local state. Once this is complete then
Terraform is back to behaving as it does by default.
OpenTF is back to behaving as it does by default.

8
website/docs/language/settings/backends/consul.mdx
View File

@ -1,13 +1,13 @@
---
page_title: 'Backend Type: consul'
description: Terraform can store state in Consul.
description: OpenTF can store state in Consul.
---
# consul
Stores the state in the [Consul](https://www.consul.io/) KV store at a given path.
This backend supports [state locking](/terraform/language/state/locking).
This backend supports [state locking](/opentf/language/state/locking).
## Example Configuration
@ -22,7 +22,7 @@ terraform {
```
Note that for the access credentials we recommend using a
[partial configuration](/terraform/language/settings/backends/configuration#partial-configuration).
[partial configuration](/opentf/language/settings/backends/configuration#partial-configuration).
## Data Source Configuration
@ -37,7 +37,7 @@ data "terraform_remote_state" "foo" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
The following configuration options / environment variables are supported:

32
website/docs/language/settings/backends/cos.mdx
View File

@ -1,7 +1,7 @@
---
page_title: 'Backend Type: cos'
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.
---
@ -9,7 +9,7 @@ description: >-
Stores the state as an object in a configurable prefix in a given bucket on [Tencent Cloud Object Storage](https://intl.cloud.tencent.com/product/cos) (COS).
This backend supports [state locking](/terraform/language/state/locking). Storing your state in a COS bucket requires the following permissions:
This backend supports [state locking](/opentf/language/state/locking). Storing your state in a COS bucket requires the following permissions:
- `CreateTag`, `DeleteTag`, and `DescribeTags` on the tag key `tencentcloud-terraform-lock`
- `Put`, `Get`, and `Delete` files for the specified bucket's prefix
@ -23,18 +23,18 @@ on the COS bucket to allow for state recovery in the case of accidental deletion
terraform {
backend "cos" {
region = "ap-guangzhou"
bucket = "bucket-for-terraform-state-1258798060"
prefix = "terraform/state"
bucket = "bucket-for-opentf-state-1258798060"
prefix = "opentf/state"
}
}
```
This assumes we have a [COS Bucket](https://registry.terraform.io/providers/tencentcloudstack/tencentcloud/latest/docs/resources/cos_bucket) created named `bucket-for-terraform-state-1258798060`,
Terraform state will be written into the file `terraform/state/terraform.tfstate`.
This assumes we have a [COS Bucket](https://registry.terraform.io/providers/tencentcloudstack/tencentcloud/latest/docs/resources/cos_bucket) created named `bucket-for-opentf-state-1258798060`,
OpenTF state will be written into the file `opentf/state/terraform.tfstate`.
## Data Source Configuration
To make use of the COS remote state in another configuration, use the [`terraform_remote_state` data source](/terraform/language/state/remote-state-data).
To make use of the COS remote state in another configuration, use the [`terraform_remote_state` data source](/opentf/language/state/remote-state-data).
```hcl
data "terraform_remote_state" "foo" {
@ -42,15 +42,15 @@ data "terraform_remote_state" "foo" {
config = {
region = "ap-guangzhou"
bucket = "bucket-for-terraform-state-1258798060"
prefix = "terraform/state"
bucket = "bucket-for-opentf-state-1258798060"
prefix = "opentf/state"
}
}
```
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
The following configuration options or environment variables are supported:
@ -66,10 +66,10 @@ The following configuration options or environment variables are supported:
- `accelerate` - (Optional) Whether to enable global Acceleration. Defaults to `false`.
### Assume Role
If provided with an assume role, Terraform will attempt to assume this role using the supplied credentials.
If provided with an assume role, OpenTF will attempt to assume this role using the supplied credentials.
Assume role can be provided by adding an `assume_role` block in the cos backend block.
- `assume_role` - (Optional) The `assume_role` block. If provided, terraform will attempt to assume this role using the supplied credentials.
- `assume_role` - (Optional) The `assume_role` block. If provided, OpenTF will attempt to assume this role using the supplied credentials.
The details of `assume_role` block as following:
- `role_arn` - (Required) The ARN of the role to assume. It can be sourced from the `TENCENTCLOUD_ASSUME_ROLE_ARN`.
@ -83,8 +83,8 @@ Usage:
terraform {
backend "cos" {
region = "ap-guangzhou"
bucket = "bucket-for-terraform-state-{appid}"
prefix = "terraform/state"
bucket = "bucket-for-opentf-state-{appid}"
prefix = "opentf/state"
assume_role {
role_arn = "qcs::cam::uin/xxx:roleName/yyy"
session_name = "my-session-name"
@ -105,5 +105,5 @@ $ export TENCENTCLOUD_REGION="ap-guangzhou"
$ export TENCENTCLOUD_ASSUME_ROLE_ARN="qcs::cam::uin/xxx:roleName/yyy"
$ export TENCENTCLOUD_ASSUME_ROLE_SESSION_NAME="my-session-name"
$ export TENCENTCLOUD_ASSUME_ROLE_SESSION_DURATION=3600
$ terraform plan
```
$ opentf plan
```

47
website/docs/language/settings/backends/gcs.mdx
View File

@ -1,7 +1,7 @@
---
page_title: 'Backend Type: gcs'
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.
---
@ -10,7 +10,7 @@ description: >-
Stores the state as an object in a configurable prefix in a pre-existing bucket on [Google Cloud Storage](https://cloud.google.com/storage/) (GCS).
The bucket must exist prior to configuring the backend.
This backend supports [state locking](/terraform/language/state/locking).
This backend supports [state locking](/opentf/language/state/locking).
~> **Warning!** It is highly recommended that you enable
[Object Versioning](https://cloud.google.com/storage/docs/object-versioning)
@ -22,7 +22,7 @@ on the GCS bucket to allow for state recovery in the case of accidental deletion
terraform {
backend "gcs" {
bucket = "tf-state-prod"
prefix = "terraform/state"
prefix = "opentf/state"
}
}
```
@ -33,49 +33,42 @@ terraform {
data "terraform_remote_state" "foo" {
backend = "gcs"
config = {
bucket = "terraform-state"
bucket = "opentf-state"
prefix = "prod"
}
}
# Terraform >= 0.12
resource "local_file" "foo" {
content = data.terraform_remote_state.foo.outputs.greeting
filename = "${path.module}/outputs.txt"
}
# Terraform <= 0.11
resource "local_file" "foo" {
content = "${data.terraform_remote_state.foo.greeting}"
filename = "${path.module}/outputs.txt"
}
```
## Authentication
IAM Changes to buckets are [eventually consistent](https://cloud.google.com/storage/docs/consistency#eventually_consistent_operations) and may take upto a few minutes to take effect. Terraform will return 403 errors till it is eventually consistent.
IAM Changes to buckets are [eventually consistent](https://cloud.google.com/storage/docs/consistency#eventually_consistent_operations) and may take upto a few minutes to take effect. OpenTF will return 403 errors till it is eventually consistent.
### Running Terraform on your workstation.
### Running OpenTF on your workstation.
If you are using terraform on your workstation, you will need to install the Google Cloud SDK and authenticate using [User Application Default
If you are using OpenTF on your workstation, you will need to install the Google Cloud SDK and authenticate using [User Application Default
Credentials](https://cloud.google.com/sdk/gcloud/reference/auth/application-default).
User ADCs do [expire](https://developers.google.com/identity/protocols/oauth2#expiration) and you can refresh them by running `gcloud auth application-default login`.
### Running Terraform on Google Cloud
### Running OpenTF on Google Cloud
If you are running terraform on Google Cloud, you can configure that instance or cluster to use a [Google Service
Account](https://cloud.google.com/compute/docs/authentication). This will allow Terraform to authenticate to Google Cloud without having to bake in a separate
If you are running OpenTF on Google Cloud, you can configure that instance or cluster to use a [Google Service
Account](https://cloud.google.com/compute/docs/authentication). This will allow OpenTF to authenticate to Google Cloud without having to bake in a separate
credential/authentication file. Make sure that the scope of the VM/Cluster is set to cloud-platform.
### Running Terraform outside of Google Cloud
### Running OpenTF outside of Google Cloud
If you are running terraform outside of Google Cloud, generate a service account key and set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to
the path of the service account key. Terraform will use that key for authentication.
If you are running OpenTF outside of Google Cloud, generate a service account key and set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to
the path of the service account key. OpenTF will use that key for authentication.
### Impersonating Service Accounts
Terraform can impersonate a Google Service Account as described [here](https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials). A valid credential must be provided as mentioned in the earlier section and that identity must have the `roles/iam.serviceAccountTokenCreator` role on the service account you are impersonating.
OpenTF can impersonate a Google Service Account as described [here](https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials). A valid credential must be provided as mentioned in the earlier section and that identity must have the `roles/iam.serviceAccountTokenCreator` role on the service account you are impersonating.
## Encryption
@ -85,23 +78,23 @@ Terraform can impersonate a Google Service Account as described [here](https://c
To get started, follow this guide: [Use customer-supplied encryption keys](https://cloud.google.com/storage/docs/encryption/using-customer-supplied-keys)
If you want to remove customer-supplied keys from your backend configuration or change to a different customer-supplied key, Terraform cannot perform a state migration automatically and manual intervention is necessary instead. This intervention is necessary because Google does not store customer-supplied encryption keys, any requests sent to the Cloud Storage API must supply them instead (see [Customer-supplied Encryption Keys](https://cloud.google.com/storage/docs/encryption/customer-supplied-keys)). At the time of state migration, the backend configuration loses the old key's details and Terraform cannot use the key during the migration process.
If you want to remove customer-supplied keys from your backend configuration or change to a different customer-supplied key, OpenTF cannot perform a state migration automatically and manual intervention is necessary instead. This intervention is necessary because Google does not store customer-supplied encryption keys, any requests sent to the Cloud Storage API must supply them instead (see [Customer-supplied Encryption Keys](https://cloud.google.com/storage/docs/encryption/customer-supplied-keys)). At the time of state migration, the backend configuration loses the old key's details and OpenTF cannot use the key during the migration process.
~> **Important:** To migrate your state away from using customer-supplied encryption keys or change the key used by your backend, you need to perform a [rewrite (gsutil CLI)](https://cloud.google.com/storage/docs/gsutil/commands/rewrite) or [cp (gcloud CLI)](https://cloud.google.com/sdk/gcloud/reference/storage/cp#--decryption-keys) operation to remove use of the old customer-supplied encryption key on your state file. Once you remove the encryption, you can successfully run `terraform init -migrate-state` with your new backend configuration.
~> **Important:** To migrate your state away from using customer-supplied encryption keys or change the key used by your backend, you need to perform a [rewrite (gsutil CLI)](https://cloud.google.com/storage/docs/gsutil/commands/rewrite) or [cp (gcloud CLI)](https://cloud.google.com/sdk/gcloud/reference/storage/cp#--decryption-keys) operation to remove use of the old customer-supplied encryption key on your state file. Once you remove the encryption, you can successfully run `opentf init -migrate-state` with your new backend configuration.
### Customer-managed encryption keys (Cloud KMS)
To get started, follow this guide: [Use customer-managed encryption keys](https://cloud.google.com/storage/docs/encryption/using-customer-managed-keys)
If you want to remove customer-managed keys from your backend configuration or change to a different customer-managed key, Terraform _can_ manage a state migration without manual intervention. This ability is because GCP stores customer-managed encryption keys and are accessible during the state migration process. However, these changes do not fully come into effect until the first write operation occurs on the state file after state migration occurs. In the first write operation after state migration, the file decrypts with the old key and then writes with the new encryption method. This method is equivalent to the [rewrite](https://cloud.google.com/storage/docs/gsutil/commands/rewrite) operation described in the customer-supplied encryption keys section. Because of the importance of the first write to state after state migration, you should not delete old KMS keys until any state file(s) encrypted with that key update.
If you want to remove customer-managed keys from your backend configuration or change to a different customer-managed key, OpenTF _can_ manage a state migration without manual intervention. This ability is because GCP stores customer-managed encryption keys and are accessible during the state migration process. However, these changes do not fully come into effect until the first write operation occurs on the state file after state migration occurs. In the first write operation after state migration, the file decrypts with the old key and then writes with the new encryption method. This method is equivalent to the [rewrite](https://cloud.google.com/storage/docs/gsutil/commands/rewrite) operation described in the customer-supplied encryption keys section. Because of the importance of the first write to state after state migration, you should not delete old KMS keys until any state file(s) encrypted with that key update.
Customer-managed keys do not need to be sent in requests to read files from GCS buckets because decryption occurs automatically within GCS. This process means that if you use the `terraform_remote_state` [data source](/terraform/language/state/remote-state-data) to access KMS-encrypted state, you do not need to specify the KMS key in the data source's `config` object.
Customer-managed keys do not need to be sent in requests to read files from GCS buckets because decryption occurs automatically within GCS. This process means that if you use the `terraform_remote_state` [data source](/opentf/language/state/remote-state-data) to access KMS-encrypted state, you do not need to specify the KMS key in the data source's `config` object.
~> **Important:** To use customer-managed encryption keys, you need to create a key and give your project's GCS service agent permission to use it with the Cloud KMS CryptoKey Encrypter/Decrypter predefined role.
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform includes these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF includes these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
The following configuration options are supported:
@ -133,4 +126,4 @@ The following configuration options are supported:
Format should be `projects/{{project}}/locations/{{location}}/keyRings/{{keyRing}}/cryptoKeys/{{name}}`.
For more information, including IAM requirements, see [Customer-managed Encryption
Keys](https://cloud.google.com/storage/docs/encryption/customer-managed-keys).
- `storage_custom_endpoint` / `GOOGLE_BACKEND_STORAGE_CUSTOM_ENDPOINT` / `GOOGLE_STORAGE_CUSTOM_ENDPOINT` - (Optional) A URL containing three parts: the protocol, the DNS name pointing to a Private Service Connect endpoint, and the path for the Cloud Storage API (`/storage/v1/b`, [see here](https://cloud.google.com/storage/docs/json_api/v1/buckets/get#http-request)). You can either use [a DNS name automatically made by the Service Directory](https://cloud.google.com/vpc/docs/configure-private-service-connect-apis#configure-p-dns) or a [custom DNS name](https://cloud.google.com/vpc/docs/configure-private-service-connect-apis#configure-dns-default) made by you. For example, if you create an endpoint called `xyz` and want to use the automatically-created DNS name, you should set the field value as `https://storage-xyz.p.googleapis.com/storage/v1/b`. For help creating a Private Service Connect endpoint using Terraform, [see this guide](https://cloud.google.com/vpc/docs/configure-private-service-connect-apis#terraform_1).
- `storage_custom_endpoint` / `GOOGLE_BACKEND_STORAGE_CUSTOM_ENDPOINT` / `GOOGLE_STORAGE_CUSTOM_ENDPOINT` - (Optional) A URL containing three parts: the protocol, the DNS name pointing to a Private Service Connect endpoint, and the path for the Cloud Storage API (`/storage/v1/b`, [see here](https://cloud.google.com/storage/docs/json_api/v1/buckets/get#http-request)). You can either use [a DNS name automatically made by the Service Directory](https://cloud.google.com/vpc/docs/configure-private-service-connect-apis#configure-p-dns) or a [custom DNS name](https://cloud.google.com/vpc/docs/configure-private-service-connect-apis#configure-dns-default) made by you. For example, if you create an endpoint called `xyz` and want to use the automatically-created DNS name, you should set the field value as `https://storage-xyz.p.googleapis.com/storage/v1/b`. For help creating a Private Service Connect endpoint using OpenTF, [see this guide](https://cloud.google.com/vpc/docs/configure-private-service-connect-apis#terraform_1).

6
website/docs/language/settings/backends/http.mdx
View File

@ -1,6 +1,6 @@
---
page_title: 'Backend Type: http'
description: Terraform can store state remotely at any valid HTTP endpoint.
description: OpenTF can store state remotely at any valid HTTP endpoint.
---
# http
@ -9,7 +9,7 @@ Stores the state using a simple [REST](https://en.wikipedia.org/wiki/Representat
State will be fetched via GET, updated via POST, and purged with DELETE. The method used for updating is configurable.
This backend optionally supports [state locking](/terraform/language/state/locking). When locking
This backend optionally supports [state locking](/opentf/language/state/locking). When locking
support is enabled it will use LOCK and UNLOCK requests providing the lock info in the body. The
endpoint should return a 423: Locked or 409: Conflict with the holding lock info when it's already
taken, 200: OK for success. Any other status will be considered an error. The ID of the holding lock
@ -40,7 +40,7 @@ data "terraform_remote_state" "foo" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
The following configuration options / environment variables are supported:

12
website/docs/language/settings/backends/kubernetes.mdx
View File

@ -1,6 +1,6 @@
---
page_title: 'Backend Type: Kubernetes'
description: Terraform can store state remotely in Kubernetes and lock that state.
description: OpenTF can store state remotely in Kubernetes and lock that state.
---
# kubernetes
@ -9,7 +9,7 @@ description: Terraform can store state remotely in Kubernetes and lock that stat
Stores the state in a [Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/).
This backend supports [state locking](/terraform/language/state/locking), with locking done using a Lease resource.
This backend supports [state locking](/opentf/language/state/locking), with locking done using a Lease resource.
## Example Configuration
@ -22,15 +22,15 @@ terraform {
}
```
This assumes the user/service account running terraform has [permissions](https://kubernetes.io/docs/reference/access-authn-authz/authorization/) to read/write secrets in the [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) used to store the secret.
This assumes the user/service account running OpenTF has [permissions](https://kubernetes.io/docs/reference/access-authn-authz/authorization/) to read/write secrets in the [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) used to store the secret.
If the `config_path` or `config_paths` attribute is set the backend will attempt to use a [kubeconfig file](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) to gain access to the cluster.
If the `in_cluster_config` flag is set the backend will attempt to use a [service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) to access the cluster. This can be used if Terraform is being run from within a pod running in the Kubernetes cluster.
If the `in_cluster_config` flag is set the backend will attempt to use a [service account](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) to access the cluster. This can be used if OpenTF is being run from within a pod running in the Kubernetes cluster.
For most use cases either `in_cluster_config`, `config_path`, or `config_paths` will need to be set. If all flags are set the configuration at `config_path` will be used.
Note that for the access credentials we recommend using a [partial configuration](/terraform/language/settings/backends/configuration#partial-configuration).
Note that for the access credentials we recommend using a [partial configuration](/opentf/language/settings/backends/configuration#partial-configuration).
## Example Referencing
@ -46,7 +46,7 @@ data "terraform_remote_state" "foo" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
The following configuration options are supported:

4
website/docs/language/settings/backends/local.mdx
View File

@ -77,7 +77,7 @@ the three arguments would typically all be paths within a temporary
directory used just for one operation.
Because these old workflows predate the introduction of the possibility of
[multiple workspaces](/terraform/language/state/workspaces), setting them
[multiple workspaces](/opentf/language/state/workspaces), setting them
overrides Terraform's usual behavior of selecting a different state filename
based on the selected workspace. If you use all three of these options then
the selected workspace has no effect on which filenames Terraform will select
@ -89,7 +89,7 @@ backend type selected.
We do not recommend using these options in new systems, even if you are running
Terraform in automation. Instead,
[select a different backend which supports remote state](/terraform/language/settings/backends/configuration) and configure it
[select a different backend which supports remote state](/opentf/language/settings/backends/configuration) and configure it
within your root module, which ensures that everyone working on your
configuration will automatically retrieve and store state in the correct shared
location without any special command line options.

28
website/docs/language/settings/backends/oss.mdx
View File

@ -1,6 +1,6 @@
---
page_title: 'Backend Type: oss'
description: Terraform can store state remotely in OSS and lock that state with OSS.
description: OpenTF can store state remotely in OSS and lock that state with OSS.
---
# OSS
@ -11,35 +11,33 @@ This backend also supports state locking and consistency checking via
[Alibaba Cloud Table Store](https://www.alibabacloud.com/help/doc-detail/27280.htm), which can be enabled by setting
the `tablestore_table` field to an existing TableStore table name.
This backend supports [state locking](/terraform/language/state/locking) via TableStore.
-> **Note:** The OSS backend is available from terraform version 0.12.2.
This backend supports [state locking](/opentf/language/state/locking) via TableStore.
## Example Configuration
```hcl
terraform {
backend "oss" {
bucket = "bucket-for-terraform-state"
bucket = "bucket-for-opentf-state"
prefix = "path/mystate"
key = "version-1.tfstate"
region = "cn-beijing"
tablestore_endpoint = "https://terraform-remote.cn-hangzhou.ots.aliyuncs.com"
tablestore_endpoint = "https://opentf-remote.cn-hangzhou.ots.aliyuncs.com"
tablestore_table = "statelock"
}
}
```
This assumes we have a [OSS Bucket](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/oss_bucket) created called `bucket-for-terraform-state`,
a [OTS Instance](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/ots_instance) called `terraform-remote` and
This assumes we have a [OSS Bucket](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/oss_bucket) created called `bucket-for-opentf-state`,
a [OTS Instance](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/ots_instance) called `opentf-remote` and
a [OTS TableStore](https://registry.terraform.io/providers/aliyun/alicloud/latest/docs/resources/ots_table) called `statelock`. The
Terraform state will be written into the file `path/mystate/version-1.tfstate`. The `TableStore` must have a primary key named `LockID` of type `String`.
OpenTF state will be written into the file `path/mystate/version-1.tfstate`. The `TableStore` must have a primary key named `LockID` of type `String`.
## Data Source Configuration
To make use of the OSS remote state in another configuration, use the
[`terraform_remote_state` data
source](/terraform/language/state/remote-state-data).
source](/opentf/language/state/remote-state-data).
```hcl
terraform {
@ -71,7 +69,7 @@ data "terraform_remote_state" "network" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
The following configuration options or environment variables are supported:
@ -111,11 +109,11 @@ The following configuration options or environment variables are supported:
* `profile` - (Optional, Available in 0.12.8+) This is the Alibaba Cloud profile name as set in the shared credentials file. It can also be sourced from the `ALICLOUD_PROFILE` environment variable.
* `assume_role_role_arn` - (Optional, Available in 1.1.0+) The ARN of the role to assume. If ARN is set to an empty string, it does not perform role switching. It supports the environment variable `ALICLOUD_ASSUME_ROLE_ARN`.
Terraform executes configuration on account with provided credentials.
OpenTF executes configuration on account with provided credentials.
* `assume_role_policy` - (Optional, Available in 1.1.0+) A more restrictive policy to apply to the temporary credentials. This gives you a way to further restrict the permissions for the resulting temporary security credentials. You cannot use this policy to grant permissions that exceed those of the role that is being assumed.
* `assume_role_session_name` - (Optional, Available in 1.1.0+) The session name to use when assuming the role. If omitted, 'terraform' is passed to the AssumeRole call as session name. It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_NAME`.
* `assume_role_session_name` - (Optional, Available in 1.1.0+) The session name to use when assuming the role. If omitted, 'opentf' is passed to the AssumeRole call as session name. It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_NAME`.
* `assume_role_session_expiration` - (Optional, Available in 1.1.0+) The time after which the established session for assuming role expires. Valid value range: \[900-3600] seconds. Default to 3600 (in this case Alibaba Cloud uses its own default value). It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION`.
@ -124,11 +122,11 @@ The following configuration options or environment variables are supported:
**Deprecated in favor of flattening assume_role_\* options**
* `role_arn` - (Required) The ARN of the role to assume. If ARN is set to an empty string, it does not perform role switching. It supports the environment variable `ALICLOUD_ASSUME_ROLE_ARN`.
Terraform executes configuration on account with provided credentials.
OpenTF executes configuration on account with provided credentials.
* `policy` - (Optional) A more restrictive policy to apply to the temporary credentials. This gives you a way to further restrict the permissions for the resulting temporary security credentials. You cannot use this policy to grant permissions that exceed those of the role that is being assumed.
* `session_name` - (Optional) The session name to use when assuming the role. If omitted, 'terraform' is passed to the AssumeRole call as session name. It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_NAME`.
* `session_name` - (Optional) The session name to use when assuming the role. If omitted, 'opentf' is passed to the AssumeRole call as session name. It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_NAME`.
* `session_expiration` - (Optional) The time after which the established session for assuming role expires. Valid value range: \[900-3600] seconds. Default to 3600 (in this case Alibaba Cloud uses its own default value). It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION`.

36
website/docs/language/settings/backends/pg.mdx
View File

@ -1,28 +1,28 @@
---
page_title: 'Backend Type: pg'
description: Terraform can store state remotely in a Postgres database with locking.
description: OpenTF can store state remotely in a Postgres database with locking.
---
# pg
Stores the state in a [Postgres database](https://www.postgresql.org) version 10 or newer.
This backend supports [state locking](/terraform/language/state/locking).
This backend supports [state locking](/opentf/language/state/locking).
## Example Configuration
```hcl
terraform {
backend "pg" {
conn_str = "postgres://user:pass@db.example.com/terraform_backend"
conn_str = "postgres://user:pass@db.example.com/opentf_backend"
}
}
```
Before initializing the backend with `terraform init`, the database must already exist:
Before initializing the backend with `opentf init`, the database must already exist:
```
createdb terraform_backend
createdb opentf_backend
```
This `createdb` command is found in [Postgres client applications](https://www.postgresql.org/docs/10/reference-client.html) which are installed along with the database server.
@ -46,8 +46,8 @@ terraform {
```
```shellsession
$ export PG_CONN_STR=postgres://user:pass@db.example.com/terraform_backend
$ terraform init
$ export PG_CONN_STR=postgres://user:pass@db.example.com/opentf_backend
$ opentf init
```
or just the sensitive parameters:
@ -55,7 +55,7 @@ or just the sensitive parameters:
```hcl
terraform {
backend "pg" {
conn_str = "postgres://db.example.com/terraform_backend"
conn_str = "postgres://db.example.com/opentf_backend"
}
}
```
@ -64,44 +64,44 @@ terraform {
$ export PGUSER=user
$ read -s PGPASSWORD
$ export PGPASSWORD
$ terraform init
$ opentf init
```
## Data Source Configuration
To make use of the pg remote state in another configuration, use the [`terraform_remote_state` data source](/terraform/language/state/remote-state-data).
To make use of the pg remote state in another configuration, use the [`terraform_remote_state` data source](/opentf/language/state/remote-state-data).
```hcl
data "terraform_remote_state" "network" {
backend = "pg"
config = {
conn_str = "postgres://localhost/terraform_backend"
conn_str = "postgres://localhost/opentf_backend"
}
}
```
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
The following configuration options or environment variables are supported:
- `conn_str` - Postgres connection string; a `postgres://` URL. The `PG_CONN_STR` and [standard `libpq`](https://www.postgresql.org/docs/current/libpq-envars.html) environment variables can also be used to indicate how to connect to the PostgreSQL database.
- `schema_name` - Name of the automatically-managed Postgres schema, default to `terraform_remote_state`. Can also be set using the `PG_SCHEMA_NAME` environment variable.
- `skip_schema_creation` - If set to `true`, the Postgres schema must already exist. Can also be set using the `PG_SKIP_SCHEMA_CREATION` environment variable. Terraform won't try to create the schema, this is useful when it has already been created by a database administrator.
- `skip_table_creation` - If set to `true`, the Postgres table must already exist. Can also be set using the `PG_SKIP_TABLE_CREATION` environment variable. Terraform won't try to create the table, this is useful when it has already been created by a database administrator.
- `skip_index_creation` - If set to `true`, the Postgres index must already exist. Can also be set using the `PG_SKIP_INDEX_CREATION` environment variable. Terraform won't try to create the index, this is useful when it has already been created by a database administrator.
- `skip_schema_creation` - If set to `true`, the Postgres schema must already exist. Can also be set using the `PG_SKIP_SCHEMA_CREATION` environment variable. OpenTF won't try to create the schema, this is useful when it has already been created by a database administrator.
- `skip_table_creation` - If set to `true`, the Postgres table must already exist. Can also be set using the `PG_SKIP_TABLE_CREATION` environment variable. OpenTF won't try to create the table, this is useful when it has already been created by a database administrator.
- `skip_index_creation` - If set to `true`, the Postgres index must already exist. Can also be set using the `PG_SKIP_INDEX_CREATION` environment variable. OpenTF won't try to create the index, this is useful when it has already been created by a database administrator.
## Technical Design
This backend creates one table **states** in the automatically-managed Postgres schema configured by the `schema_name` variable.
The table is keyed by the [workspace](/terraform/language/state/workspaces) name. If workspaces are not in use, the name `default` is used.
The table is keyed by the [workspace](/opentf/language/state/workspaces) name. If workspaces are not in use, the name `default` is used.
Locking is supported using [Postgres advisory locks](https://www.postgresql.org/docs/9.5/explicit-locking.html#ADVISORY-LOCKS). [`force-unlock`](/terraform/cli/commands/force-unlock) is not supported, because these database-native locks will automatically unlock when the session is aborted or the connection fails. To see outstanding locks in a Postgres server, use the [`pg_locks` system view](https://www.postgresql.org/docs/9.5/view-pg-locks.html).
Locking is supported using [Postgres advisory locks](https://www.postgresql.org/docs/9.5/explicit-locking.html#ADVISORY-LOCKS). [`force-unlock`](/opentf/cli/commands/force-unlock) is not supported, because these database-native locks will automatically unlock when the session is aborted or the connection fails. To see outstanding locks in a Postgres server, use the [`pg_locks` system view](https://www.postgresql.org/docs/9.5/view-pg-locks.html).
The **states** table contains:
- a serial integer `id`, used as the key for advisory locks
- the workspace `name` key as _text_ with a unique index
- the Terraform state `data` as _text_
- the OpenTF state `data` as _text_

87
website/docs/language/settings/backends/remote.mdx
View File

@ -1,32 +1,31 @@
---
page_title: 'Backend Type: remote'
description: >-
Terraform can store the state and run operations remotely, making it easier to
OpenTF can store the state and run operations remotely, making it easier to
version and work with in a team.
---
# remote
-> **Note:** We introduced the remote backend in Terraform v0.11.13 and Terraform Enterprise v201809-1. As of Terraform v1.1.0 and Terraform Enterprise v202201-1, **we recommend using the Terraform Cloud's built-in [`cloud` integration](/terraform/cli/cloud/settings)** instead of this backend. The `cloud` option includes an improved user experience and more features.
-> **Note:** **We recommend using the [`cloud` built-in integration](/opentf/cli/cloud/settings)** instead of this backend. The `cloud` option includes an improved user experience and more features.
The remote backend is unique among all other Terraform backends because it can both store state snapshots and execute operations for Terraform Cloud's [CLI-driven run workflow](/terraform/cloud-docs/run/cli). It used to be called an "enhanced" backend.
The remote backend is unique among all other OpenTF backends because it can both store state snapshots and execute operations for TACOS (TF Automation and Collaboration Software) [CLI-driven run workflow](/opentf/cloud-docs/run/cli). It used to be called an "enhanced" backend.
When using full remote operations, operations like `terraform plan` or `terraform apply` can be executed in Terraform
Cloud's run environment, with log output streaming to the local terminal. Remote plans and applies use variable values from the associated Terraform Cloud workspace.
When using full remote operations, operations like `opentf plan` or `opentf apply` can be executed in TACOS (TF Automation and Collaboration Software) run environment, with log output streaming to the local terminal. Remote plans and applies use variable values from the associated remote workspace.
You can also use Terraform Cloud with local operations, in which case only state is stored in the Terraform Cloud backend.
You can also use TACOS (TF Automation and Collaboration Software) with local operations, in which case only state is stored in the remote backend.
## Command Support
The remote backend supports the following Terraform commands:
The remote backend supports the following OpenTF commands:
- `apply`
- `console` (supported in Terraform >= v0.11.12)
- `console`
- `destroy`
- `fmt`
- `get`
- `graph` (supported in Terraform >= v0.11.12)
- `import` (supported in Terraform >= v0.11.12)
- `graph`
- `import`
- `init`
- `output`
- `plan`
@ -41,45 +40,41 @@ The remote backend supports the following Terraform commands:
## Workspaces
The remote backend can work with either a single remote Terraform Cloud workspace, or with multiple similarly-named remote workspaces (like `networking-dev` and `networking-prod`). The `workspaces` block of the backend configuration
The remote backend can work with either a single remote workspace, or with multiple similarly-named remote workspaces (like `networking-dev` and `networking-prod`). The `workspaces` block of the backend configuration
determines which mode it uses:
- To use a single remote Terraform Cloud workspace, set `workspaces.name` to the
- To use a single remote workspace, set `workspaces.name` to the
remote workspace's full name (like `networking-prod`).
- To use multiple remote workspaces, set `workspaces.prefix` to a prefix used in
all of the desired remote workspace names. For example, set
`prefix = "networking-"` to use Terraform cloud workspaces with
`prefix = "networking-"` to use remote workspaces with
names like `networking-dev` and `networking-prod`. This is helpful when
mapping multiple Terraform CLI [workspaces](/terraform/language/state/workspaces)
used in a single Terraform configuration to multiple Terraform Cloud
workspaces.
mapping multiple OpenTF CLI [workspaces](/opentf/language/state/workspaces)
used in a single OpenTF configuration to multiple remote workspaces.
The backend configuration requires either `name` or `prefix`. Omitting both or
setting both results in a configuration error.
If previous state is present when you run `terraform init` and the corresponding
remote workspaces are empty or absent, Terraform will create workspaces and
update the remote state accordingly. However, if your workspace requires variables or a specific version of Terraform for remote operations, we
recommend that you create your remote workspaces on Terraform Cloud before
If previous state is present when you run `opentf init` and the corresponding
remote workspaces are empty or absent, OpenTF will create workspaces and
update the remote state accordingly. However, if your workspace requires variables or a specific version of OpenTF for remote operations, we
recommend that you create your remote workspaces on TACOS (TF Automation and Collaboration Software) before
running any remote operations against them.
### Workspace Names
Terraform uses shortened names without the common prefix to interact with workspaces on the command line. For example, if `prefix = "networking-"`, use `terraform workspace select prod` to switch to the Terraform CLI workspace `prod` within the current configuration. However, remote Terraform operations such as `plan` and `apply` for that Terraform CLI workspace will take place in the Terraform Cloud workspace `networking-prod`.
OpenTF uses shortened names without the common prefix to interact with workspaces on the command line. For example, if `prefix = "networking-"`, use `opentf workspace select prod` to switch to the OpenTF CLI workspace `prod` within the current configuration. However, remote OpenTF operations such as `plan` and `apply` for that OpenTF CLI workspace will take place in the remote workspace `networking-prod`.
Because of this, the [`terraform.workspace`](/terraform/language/state/workspaces#current-workspace-interpolation) interpolation expression produces different results depending on whether a remote workspace is configured to perform operations locally or remotely. For example, in a remote workspace called `networking-prod` created with `prefix = "networking-"` the expression produces the following:
Because of this, the [`terraform.workspace`](/opentf/language/state/workspaces#current-workspace-interpolation) interpolation expression produces different results depending on whether a remote workspace is configured to perform operations locally or remotely. For example, in a remote workspace called `networking-prod` created with `prefix = "networking-"` the expression produces the following:
- For local operations, `terraform.workspace` = `prod`
- For remote operations, `terraform.workspace`= `networking-prod`
Prior to Terraform version 1.1.0, Terraform Cloud workspaces used only the single `default` Terraform CLI workspace internally. So if a Terraform configuration used `terraform.workspace` to return `dev` or `prod`, remote runs in Terraform Cloud would always evaluate it as `default`, regardless of
which workspace you set with the `terraform workspace select` command. Therefore, we do not recommend using `terraform.workspace` in Terraform configurations that use Terraform 1.0.x or earlier and run remote operations against Terraform Cloud workspaces.
### Determining Run Environment
If you need to determine whether a run is local or remote in your Terraform configuration, we recommend using [Terraform Cloud run environment variables](/terraform/cloud-docs/run/run-environment#environment-variables). The example below uses `TFC_RUN_ID`.
If you need to determine whether a run is local or remote in your OpenTF configuration, we recommend using [run environment variables](/opentf/cloud-docs/run/run-environment#environment-variables). The example below uses `TFC_RUN_ID`.
```
output "current_workspace_name" {
@ -100,8 +95,8 @@ output "remote_execution_determine" {
## Example Configurations
-> **Note:** We recommend omitting the token from the configuration, and instead using
[`terraform login`](/terraform/cli/commands/login) or manually configuring
`credentials` in the [CLI config file](/terraform/cli/config/config-file#credentials).
[`opentf login`](/opentf/cli/commands/login) or manually configuring
`credentials` in the [CLI config file](/opentf/cli/config/config-file#credentials).
### Basic Configuration
@ -109,7 +104,7 @@ output "remote_execution_determine" {
# Using a single workspace:
terraform {
backend "remote" {
hostname = "app.terraform.io"
hostname = "app.example.io"
organization = "company"
workspaces {
@ -121,7 +116,7 @@ terraform {
# Using multiple workspaces:
terraform {
backend "remote" {
hostname = "app.terraform.io"
hostname = "app.example.io"
organization = "company"
workspaces {
@ -147,14 +142,14 @@ Backend configuration file:
```hcl
# config.remote.tfbackend
workspaces { name = "workspace" }
hostname = "app.terraform.io"
hostname = "app.example.io"
organization = "company"
```
Running `terraform init` with the backend file:
Running `opentf init` with the backend file:
```sh
terraform init -backend-config=config.remote.tfbackend
opentf init -backend-config=config.remote.tfbackend
```
### Data Source Configuration
@ -175,7 +170,7 @@ data "terraform_remote_state" "foo" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
The following configuration options are supported:
@ -185,9 +180,9 @@ The following configuration options are supported:
targeted workspace(s).
- `token` - (Optional) The token used to authenticate with the remote backend.
We recommend omitting the token from the configuration, and instead using
[`terraform login`](/terraform/cli/commands/login) or manually configuring
[`opentf login`](/opentf/cli/commands/login) or manually configuring
`credentials` in the
[CLI config file](/terraform/cli/config/config-file#credentials).
[CLI config file](/opentf/cli/config/config-file#credentials).
- `workspaces` - (Required) A block specifying which remote workspace(s) to use.
The `workspaces` block supports the following keys:
@ -195,40 +190,38 @@ The following configuration options are supported:
only the default workspace can be used. This option conflicts with `prefix`.
- `prefix` - (Optional) A prefix used in the names of one or more remote
workspaces, all of which can be used with this configuration. The full
workspace names are used in Terraform Cloud, and the short names
(minus the prefix) are used on the command line for Terraform CLI workspaces.
workspace names are used in TACOS (TF Automation and Collaboration Software), and the short names
(minus the prefix) are used on the command line for OpenTF CLI workspaces.
If omitted, only the default workspace can be used. This option conflicts with `name`.
-> **Note:** You must use the `name` key when configuring a `terraform_remote_state`
data source that retrieves state from another Terraform Cloud workspace. The `prefix` key is only
data source that retrieves state from another remote workspace. The `prefix` key is only
intended for use when configuring an instance of the remote backend.
## Command Line Arguments
For configurations that include a `backend "remote"` block, commands that
make local modifications to Terraform state and then push them back up to
make local modifications to OpenTF state and then push them back up to
the remote workspace accept the following option to modify that behavior:
- `-ignore-remote-version` - Override checking that the local and remote
Terraform versions agree, making an operation proceed even when there is
OpenTF versions agree, making an operation proceed even when there is
a mismatch.
Normally state-modification operations require using a local version of
Terraform CLI which is compatible with the Terraform version selected
OpenTF CLI which is compatible with the OpenTF version selected
for the remote workspace as part of its settings. This is to avoid the
local operation creating a new state snapshot which the workspace's
remote execution environment would then be unable to decode.
Overriding this check can result in a Terraform Cloud workspace that is
Overriding this check can result in a remote workspace that is
no longer able to complete remote operations, so we recommend against
using this option.
## Excluding Files from Upload with .terraformignore
-> **Version note:** `.terraformignore` support was added in Terraform 0.12.11.
When executing a remote `plan` or `apply` in a [CLI-driven run](/terraform/cloud-docs/run/cli),
an archive of your configuration directory is uploaded to Terraform Cloud. You can define
When executing a remote `plan` or `apply` in a [CLI-driven run](/opentf/cloud-docs/run/cli),
an archive of your configuration directory is uploaded to TACOS (TF Automation and Collaboration Software). You can define
paths to ignore from upload via a `.terraformignore` file at the root of your configuration directory. If this file is not present, the archive will exclude the following by default:
- `.git/` directories

99
website/docs/language/settings/backends/s3.mdx
View File

@ -1,6 +1,6 @@
---
page_title: 'Backend Type: s3'
description: Terraform can store state remotely in S3 and lock that state with DynamoDB.
description: OpenTF can store state remotely in S3 and lock that state with DynamoDB.
---
# S3
@ -10,7 +10,7 @@ Stores the state as a given key in a given bucket on
This backend also supports state locking and consistency checking via
[Dynamo DB](https://aws.amazon.com/dynamodb/), which can be enabled by setting
the `dynamodb_table` field to an existing DynamoDB table name.
A single DynamoDB table can be used to lock multiple remote state files. Terraform generates key names that include the values of the `bucket` and `key` variables.
A single DynamoDB table can be used to lock multiple remote state files. OpenTF generates key names that include the values of the `bucket` and `key` variables.
~> **Warning!** It is highly recommended that you enable
[Bucket Versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/manage-versioning-examples.html)
@ -29,14 +29,14 @@ terraform {
```
This assumes we have a bucket created called `mybucket`. The
Terraform state is written to the key `path/to/my/key`.
OpenTF state is written to the key `path/to/my/key`.
Note that for the access credentials we recommend using a
[partial configuration](/terraform/language/settings/backends/configuration#partial-configuration).
[partial configuration](/opentf/language/settings/backends/configuration#partial-configuration).
### S3 Bucket Permissions
Terraform will need the following AWS IAM permissions on
OpenTF will need the following AWS IAM permissions on
the target backend bucket:
* `s3:ListBucket` on `arn:aws:s3:::mybucket`
@ -73,7 +73,7 @@ documentation about
### DynamoDB Table Permissions
If you are using state locking, Terraform will need the following AWS IAM
If you are using state locking, OpenTF will need the following AWS IAM
permissions on the DynamoDB table (`arn:aws:dynamodb:::table/mytable`):
* `dynamodb:DescribeTable`
@ -104,14 +104,13 @@ This is seen in the following AWS IAM Statement:
## Data Source Configuration
To make use of the S3 remote state in another configuration, use the
[`terraform_remote_state` data
source](/terraform/language/state/remote-state-data).
[`terraform_remote_state` data source](/opentf/language/state/remote-state-data).
```hcl
data "terraform_remote_state" "network" {
backend = "s3"
config = {
bucket = "terraform-state-prod"
bucket = "opentf-state-prod"
key = "network/terraform.tfstate"
region = "us-east-1"
}
@ -131,7 +130,7 @@ data.terraform_remote_state.network:
addresses.1 = 54.196.78.166
backend = s3
config.% = 3
config.bucket = terraform-state-prod
config.bucket = opentf-state-prod
config.key = network/terraform.tfstate
config.region = us-east-1
elb_address = web-elb-790251200.us-east-1.elb.amazonaws.com
@ -144,7 +143,7 @@ This backend requires the configuration of the AWS Region and S3 state storage.
### Credentials and Shared Configuration
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, Terraform will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/terraform/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/opentf/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
The following configuration is required:
@ -182,7 +181,7 @@ The following configuration is optional:
The following configuration is required:
* `bucket` - (Required) Name of the S3 Bucket.
* `key` - (Required) Path to the state file inside the S3 Bucket. When using a non-default [workspace](/terraform/language/state/workspaces), the state path will be `/workspace_key_prefix/workspace_name/key` (see also the `workspace_key_prefix` configuration).
* `key` - (Required) Path to the state file inside the S3 Bucket. When using a non-default [workspace](/opentf/language/state/workspaces), the state path will be `/workspace_key_prefix/workspace_name/key` (see also the `workspace_key_prefix` configuration).
The following configuration is optional:
@ -190,8 +189,8 @@ The following configuration is optional:
* `encrypt` - (Optional) Enable [server side encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingServerSideEncryption.html) of the state file.
* `endpoint` - (Optional) Custom endpoint for the AWS S3 API. This can also be sourced from the `AWS_S3_ENDPOINT` environment variable.
* `force_path_style` - (Optional) Enable path-style S3 URLs (`https://<HOST>/<BUCKET>` instead of `https://<BUCKET>.<HOST>`).
* `kms_key_id` - (Optional) Amazon Resource Name (ARN) of a Key Management Service (KMS) Key to use for encrypting the state. Note that if this value is specified, Terraform will need `kms:Encrypt`, `kms:Decrypt` and `kms:GenerateDataKey` permissions on this KMS key.
* `sse_customer_key` - (Optional) The key to use for encrypting state with [Server-Side Encryption with Customer-Provided Keys (SSE-C)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ServerSideEncryptionCustomerKeys.html). This is the base64-encoded value of the key, which must decode to 256 bits. This can also be sourced from the `AWS_SSE_CUSTOMER_KEY` environment variable, which is recommended due to the sensitivity of the value. Setting it inside a terraform file will cause it to be persisted to disk in `terraform.tfstate`.
* `kms_key_id` - (Optional) Amazon Resource Name (ARN) of a Key Management Service (KMS) Key to use for encrypting the state. Note that if this value is specified, OpenTF will need `kms:Encrypt`, `kms:Decrypt` and `kms:GenerateDataKey` permissions on this KMS key.
* `sse_customer_key` - (Optional) The key to use for encrypting state with [Server-Side Encryption with Customer-Provided Keys (SSE-C)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/ServerSideEncryptionCustomerKeys.html). This is the base64-encoded value of the key, which must decode to 256 bits. This can also be sourced from the `AWS_SSE_CUSTOMER_KEY` environment variable, which is recommended due to the sensitivity of the value. Setting it inside an OpenTF file will cause it to be persisted to disk in `terraform.tfstate`.
* `workspace_key_prefix` - (Optional) Prefix applied to the state path inside the bucket. This is only relevant when using a non-default workspace. Defaults to `env:`.
### DynamoDB State Locking
@ -214,7 +213,7 @@ The S3 backend can be used in a number of different ways that make different
tradeoffs between convenience, security, and isolation in such an organization.
This section describes one such approach that aims to find a good compromise
between these tradeoffs, allowing use of
[Terraform's workspaces feature](/terraform/language/state/workspaces) to switch
[OpenTF's workspaces feature](/opentf/language/state/workspaces) to switch
conveniently between multiple isolated deployments of the same configuration.
Use this section as a starting-point for your approach, but note that
@ -224,9 +223,9 @@ adjustments to this approach to account for _existing_ practices within your
organization, if for example other tools have previously been used to manage
infrastructure.
Terraform is an administrative tool that manages your infrastructure, and so
ideally the infrastructure that is used by Terraform should exist outside of
the infrastructure that Terraform manages. This can be achieved by creating a
OpenTF is an administrative tool that manages your infrastructure, and so
ideally the infrastructure that is used by OpenTF should exist outside of
the infrastructure that OpenTF manages. This can be achieved by creating a
separate _administrative_ AWS account which contains the user accounts used by
human operators and any infrastructure and tools used to manage the other
accounts. Isolating shared administrative tools from your main environments
@ -246,12 +245,12 @@ Your administrative AWS account will contain at least the following items:
to differentiate between different groups of users that have different
levels of access to the other AWS accounts.
* An [S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingBucket.html)
that will contain the Terraform state files for each workspace.
that will contain the OpenTF state files for each workspace.
* A [DynamoDB table](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.CoreComponents.html#HowItWorks.CoreComponents.TablesItemsAttributes)
that will be used for locking to prevent concurrent operations on a single
workspace.
Provide the S3 bucket name and DynamoDB table name to Terraform within the
Provide the S3 bucket name and DynamoDB table name to OpenTF within the
S3 backend configuration using the `bucket` and `dynamodb_table` arguments
respectively, and configure a suitable `workspace_key_prefix` to contain
the states of the various workspaces that will subsequently be created for
@ -260,18 +259,18 @@ this configuration.
### Environment Account Setup
For the sake of this section, the term "environment account" refers to one
of the accounts whose contents are managed by Terraform, separate from the
of the accounts whose contents are managed by OpenTF, separate from the
administrative account described above.
Your environment accounts will eventually contain your own product-specific
infrastructure. Along with this it must contain one or more
[IAM roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)
that grant sufficient access for Terraform to perform the desired management
that grant sufficient access for OpenTF to perform the desired management
tasks.
### Delegating Access
Each Administrator will run Terraform using credentials for their IAM user
Each Administrator will run OpenTF using credentials for their IAM user
in the administrative account.
[IAM Role Delegation](https://docs.aws.amazon.com/IAM/latest/UserGuide/tutorial_cross-account-with-roles.html)
is used to grant these users access to the roles created in each environment
@ -290,14 +289,14 @@ above. The most important details are:
Since the purpose of the administrative account is only to host tools for
managing other accounts, it is useful to give the administrative accounts
restricted access only to the specific operations needed to assume the
environment account role and access the Terraform state. By blocking all
environment account role and access the OpenTF state. By blocking all
other access, you remove the risk that user error will lead to staging or
production resources being created in the administrative account by mistake.
When configuring Terraform, use either environment variables or the standard
When configuring OpenTF, use either environment variables or the standard
credentials file `~/.aws/credentials` to provide the administrator user's
IAM credentials within the administrative account to both the S3 backend _and_
to Terraform's AWS provider.
to OpenTF's AWS provider.
Use conditional configuration to pass a different `assume_role` value to
the AWS provider depending on the selected workspace. For example:
@ -305,8 +304,8 @@ the AWS provider depending on the selected workspace. For example:
```hcl
variable "workspace_iam_roles" {
default = {
staging = "arn:aws:iam::STAGING-ACCOUNT-ID:role/Terraform"
production = "arn:aws:iam::PRODUCTION-ACCOUNT-ID:role/Terraform"
staging = "arn:aws:iam::STAGING-ACCOUNT-ID:role/OpenTF"
production = "arn:aws:iam::PRODUCTION-ACCOUNT-ID:role/OpenTF"
}
}
@ -321,28 +320,28 @@ provider "aws" {
```
If workspace IAM roles are centrally managed and shared across many separate
Terraform configurations, the role ARNs could also be obtained via a data
source such as [`terraform_remote_state`](/terraform/language/state/remote-state-data)
OpenTF configurations, the role ARNs could also be obtained via a data
source such as [`terraform_remote_state`](/opentf/language/state/remote-state-data)
to avoid repeating these values.
### Creating and Selecting Workspaces
With the necessary objects created and the backend configured, run
`terraform init` to initialize the backend and establish an initial workspace
`opentf init` to initialize the backend and establish an initial workspace
called "default". This workspace will not be used, but is created automatically
by Terraform as a convenience for users who are not using the workspaces
by OpenTF as a convenience for users who are not using the workspaces
feature.
Create a workspace corresponding to each key given in the `workspace_iam_roles`
variable value above:
```
$ terraform workspace new staging
$ opentf workspace new staging
Created and switched to workspace "staging"!
...
$ terraform workspace new production
$ opentf workspace new production
Created and switched to workspace "production"!
...
@ -355,25 +354,25 @@ as reading and writing the state from S3, will be performed directly as the
administrator's own user within the administrative account.
```
$ terraform workspace select staging
$ terraform apply
$ opentf workspace select staging
$ opentf apply
...
```
### Running Terraform in Amazon EC2
### Running OpenTF in Amazon EC2
Teams that make extensive use of Terraform for infrastructure management
often [run Terraform in automation](/terraform/tutorials/automation/automate-terraform?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS)
Teams that make extensive use of OpenTF for infrastructure management
often run OpenTF in automation
to ensure a consistent operating environment and to limit access to the
various secrets and other sensitive information that Terraform configurations
various secrets and other sensitive information that OpenTF configurations
tend to require.
When running Terraform in an automation tool running on an Amazon EC2 instance,
When running OpenTF in an automation tool running on an Amazon EC2 instance,
consider running this instance in the administrative account and using an
[instance profile](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html)
in place of the various administrator IAM users suggested above. An IAM
instance profile can also be granted cross-account delegation access via
an IAM policy, giving this instance the access it needs to run Terraform.
an IAM policy, giving this instance the access it needs to run OpenTF.
To isolate access to different environment accounts, use a separate EC2
instance for each target account so that its access can be limited only to
@ -387,7 +386,7 @@ services, such as ECS.
In a simple implementation of the pattern described in the prior sections,
all users have access to read and write states for all workspaces. In many
cases it is desirable to apply more precise access constraints to the
Terraform state objects in S3, so that for example only trusted administrators
OpenTF state objects in S3, so that for example only trusted administrators
are allowed to modify the production state, or to control _reading_ of a state
that contains sensitive information.
@ -403,19 +402,19 @@ to only a single state object within an S3 bucket is shown below:
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::myorg-terraform-states"
"Resource": "arn:aws:s3:::myorg-opentf-states"
},
{
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject"],
"Resource": "arn:aws:s3:::myorg-terraform-states/myapp/production/tfstate"
"Resource": "arn:aws:s3:::myorg-opentf-states/myapp/production/tfstate"
}
]
}
```
It is also possible to apply fine-grained access control to the DynamoDB
table used for locking. When Terraform puts the state lock in place during `terraform plan`, it stores the full state file as a document and sets the s3 object key as the partition key for the document. After the state lock is released, Terraform places a digest of the updated state file in DynamoDB. The key is similar to the one for the original state file, but is suffixed with `-md5`.
table used for locking. When OpenTF puts the state lock in place during `opentf plan`, it stores the full state file as a document and sets the s3 object key as the partition key for the document. After the state lock is released, OpenTF places a digest of the updated state file in DynamoDB. The key is similar to the one for the original state file, but is suffixed with `-md5`.
The example below shows a simple IAM policy that allows the backend operations role to perform these operations:
@ -436,8 +435,8 @@ The example below shows a simple IAM policy that allows the backend operations r
"Condition" : {
"ForAllValues:StringEquals" : {
"dynamodb:LeadingKeys" : [
"myorg-terraform-states/myapp/production/tfstate", // during a state lock the full state file is stored with this key
"myorg-terraform-states/myapp/production/tfstate-md5" // after the lock is released a hash of the statefile's contents are stored with this key
"myorg-opentf-states/myapp/production/tfstate", // during a state lock the full state file is stored with this key
"myorg-opentf-states/myapp/production/tfstate-md5" // after the lock is released a hash of the statefile's contents are stored with this key
]
}
}
@ -450,9 +449,9 @@ Refer to the [AWS documentation on DynamoDB fine-grained locking](https://docs.a
### Configuring Custom User-Agent Information
Note this feature is optional and only available in Terraform v0.13.1+.
Note this feature is optional.
By default, the underlying AWS client used by the Terraform AWS Provider creates requests with User-Agent headers including information about Terraform and AWS Go SDK versions. To provide additional information in the User-Agent headers, the `TF_APPEND_USER_AGENT` environment variable can be set and its value will be directly added to HTTP requests. e.g.
By default, the underlying AWS client used by the OpenTF AWS Provider creates requests with User-Agent headers including information about OpenTF and AWS Go SDK versions. To provide additional information in the User-Agent headers, the `TF_APPEND_USER_AGENT` environment variable can be set and its value will be directly added to HTTP requests. e.g.
```sh
$ export TF_APPEND_USER_AGENT="JenkinsAgent/i-12345678 BuildID/1234 (Optional Extra Information)"

88
website/docs/language/settings/index.mdx
View File

@ -1,20 +1,20 @@
---
page_title: Terraform Settings - Configuration Language
page_title: OpenTF Settings - Configuration Language
description: >-
The terraform block allows you to configure Terraform behavior, including the
Terraform version, backend, integration with Terraform Cloud, and required
providers.
The opentf block allows you to configure OpenTF behavior, including the
OpenTF version, backend, integration with TACOS (TF Automation and Collaboration Software),
and required providers.
---
# Terraform Settings
# OpenTF Settings
The special `terraform` configuration block type is used to configure some
behaviors of Terraform itself, such as requiring a minimum Terraform version to
The special `opentf` configuration block type is used to configure some
behaviors of OpenTF itself, such as requiring a minimum OpenTF version to
apply your configuration.
## Terraform Block Syntax
## OpenTF Block Syntax
Terraform settings are gathered together into `terraform` blocks:
OpenTF settings are gathered together into `opentf` blocks:
```hcl
terraform {
@ -22,54 +22,42 @@ terraform {
}
```
Each `terraform` block can contain a number of settings related to Terraform's
behavior. Within a `terraform` block, only constant values can be used;
Each `opentf` block can contain a number of settings related to OpenTF's
behavior. Within a `opentf` 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 Terraform language built-in functions.
etc, and may not use any of the OpenTF language built-in functions.
The various options supported within a `terraform` block are described in the
The various options supported within a `opentf` block are described in the
following sections.
## Configuring Terraform Cloud
## Configuring an OpenTF Backend
The nested `cloud` block configures Terraform Cloud for enabling its
[CLI-driven run workflow](/terraform/cloud-docs/run/cli).
- Refer to [Terraform Cloud Configuration](/terraform/language/settings/tf-cloud) for a summary of the `cloud` block's syntax.
- Refer to [Using Terraform Cloud](/terraform/cli/cloud) in the
Terraform CLI documentation for complete details about how to initialize and configure the Terraform Cloud CLI integration.
## Configuring a Terraform Backend
The nested `backend` block configures which state backend Terraform should use.
The nested `backend` block configures which state backend OpenTF should use.
The syntax and behavior of the `backend` block is described in [Backend
Configuration](/terraform/language/settings/backends/configuration).
Configuration](/opentf/language/settings/backends/configuration).
## Specifying a Required Terraform Version
> **Hands-on:** Try the [Manage Terraform Versions](/terraform/tutorials/configuration-language/versions) or [Manage Terraform Versions in Terraform Cloud](/terraform/tutorials/cloud/cloud-versions) tutorials.
## Specifying a Required OpenTF Version
The `required_version` setting accepts a [version constraint
string,](/terraform/language/expressions/version-constraints) which specifies which versions of Terraform
string,](/opentf/language/expressions/version-constraints) which specifies which versions of OpenTF
can be used with your configuration.
If the running version of Terraform doesn't match the constraints specified,
Terraform will produce an error and exit without taking any further actions.
If the running version of OpenTF doesn't match the constraints specified,
OpenTF will produce an error and exit without taking any further actions.
When you use [child modules](/terraform/language/modules), each module can specify its own
When you use [child modules](/opentf/language/modules), each module can specify its own
version requirements. The requirements of all modules in the tree must be
satisfied.
Use Terraform version constraints in a collaborative environment to
ensure that everyone is using a specific Terraform version, or using at least
a minimum Terraform version that has behavior expected by the configuration.
Use OpenTF version constraints in a collaborative environment to
ensure that everyone is using a specific OpenTF version, or using at least
a minimum OpenTF version that has behavior expected by the configuration.
The `required_version` setting applies only to the version of Terraform CLI.
Terraform's resource types are implemented by provider plugins,
whose release cycles are independent of Terraform CLI and of each other.
Use [the `required_providers` block](/terraform/language/providers/requirements) to manage
The `required_version` setting applies only to the version of OpenTF CLI.
OpenTF's resource types are implemented by provider plugins,
whose release cycles are independent of OpenTF CLI and of each other.
Use [the `required_providers` block](/opentf/language/providers/requirements) to manage
the expected versions for each provider you use.
## Specifying Provider Requirements
@ -91,16 +79,16 @@ terraform {
}
```
For more information, see [Provider Requirements](/terraform/language/providers/requirements).
For more information, see [Provider Requirements](/opentf/language/providers/requirements).
## Experimental Language Features
The Terraform team will sometimes introduce new language features initially via
The OpenTF 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 `terraform`
a per-module basis by setting the `experiments` argument inside a `opentf`
block:
```hcl
@ -110,30 +98,30 @@ terraform {
```
The above would opt in to an experiment named `example`, assuming such an
experiment were available in the current Terraform version.
experiment were available in the current OpenTF 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 Terraform modules intended for production use.
features in OpenTF 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 `terraform plan` or `terraform apply`. If you
generate a warning on every `opentf plan` or `opentf 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
[Terraform's changelog](https://github.com/placeholderplaceholderplaceholder/opentf/blob/main/CHANGELOG.md),
[OpenTF's changelog](https://github.com/placeholderplaceholderplaceholder/opentf/blob/main/CHANGELOG.md),
so you can watch the release notes there to discover which experiment keywords,
if any, are available in a particular Terraform release.
if any, are available in a particular OpenTF release.
## Passing Metadata to Providers
The `terraform` block can have a nested `provider_meta` block for each
The `opentf` 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](/terraform/internals/provider-meta).
For more information, see [Provider Metadata](/opentf/internals/provider-meta).

23
website/docs/language/settings/tf-cloud.mdx
View File

@ -1,29 +1,25 @@
---
page_title: Terraform Cloud Configuration - Terraform Settings - Configuration Language
page_title: Cloud Configuration - OpenTF Settings - Configuration Language
description: >-
The nested `cloud` block configures Terraform's integration with Terraform
Cloud.
The nested `cloud` block configures OpenTF's integration with a cloud backend.
---
# Terraform Cloud Configuration
# Cloud Configuration
The main module of a Terraform configuration can integrate with Terraform Cloud to enable its [CLI-driven run workflow](/terraform/cloud-docs/run/cli). You only need to configure these settings when you want to use Terraform CLI to interact with Terraform Cloud. Terraform Cloud ignores them when interacting with
Terraform through version control or the API.
> **Hands On:** Try the [Migrate State to Terraform Cloud](/terraform/tutorials/cloud/cloud-migrate) tutorial.
The main module of an OpenTF configuration can integrate with a cloud backend to enable its [CLI-driven run workflow](/opentf/cloud-docs/run/cli). You only need to configure these settings when you want to use OpenTF CLI to interact with a cloud backend.
A cloud backend ignores them when interacting with OpenTF through version control or the API.
## Usage Example
To configure the Terraform Cloud CLI integration, add a nested `cloud` block within the `terraform` block. You cannot use the CLI integration and a [state backend](/terraform/language/settings/backends/configuration) in the same configuration.
To configure the cloud CLI integration, add a nested `cloud` block within the `terraform` block. You cannot use the CLI integration and a [state backend](/opentf/language/settings/backends/configuration) in the same configuration.
Refer to [Using Terraform Cloud](/terraform/cli/cloud) in the Terraform CLI documentation for full configuration details, migration instructions, and command line arguments.
Refer to [Using the Cloud Backend](/opentf/cli/cloud) in the OpenTF CLI documentation for full configuration details, migration instructions, and command line arguments.
```hcl
terraform {
cloud {
organization = "example_corp"
## Required for Terraform Enterprise; Defaults to app.terraform.io for Terraform Cloud
hostname = "app.terraform.io"
hostname = "app.example.io"
workspaces {
tags = ["app"]
@ -31,6 +27,3 @@ terraform {
}
}
```