Terraform State in Terraform Cloud

Each Terraform Cloud workspace has its own separate state data, used for runs within that workspace.

State Usage in Terraform Runs

In remote runs, Terraform Cloud automatically configures Terraform to use the workspace's state; the Terraform configuration does not need an explicit backend configuration. (If a backend configuration is present, it will be overridden.)

In local runs (available for workspaces whose execution mode setting is set to "local"), you can use a workspace's state by configuring the CLI integration and authenticating with a user token that has permission to read and write state versions for the relevant workspace. When using a Terraform configuration that references outputs from another workspace, the authentication token must also have permission to read state outputs for that workspace. (More about permissions.)

State Versions

In addition to the current state, Terraform Cloud retains historical state versions, which can be used to analyze infrastructure changes over time.

You can view a workspace's state versions from its States tab. Each state in the list indicates which run and which VCS commit (if applicable) it was associated with. Click a state in the list for more details, including a diff against the previous state and a link to the raw state file.

State Manipulation

Certain tasks (including importing resources, tainting resources, moving or renaming existing resources to match a changed configuration, and more) may require modifying Terraform state outside the context of a run, depending on which version of Terraform your Terraform Cloud workspace is configured to use.

Newer Terraform features like moved blocks, import blocks, and the replace option allow you to accomplish these tasks using the usual plan and apply workflow. However, if the Terraform version you're using doesn't support these features, you may need to fall back to manual state manipulation.

Manual state manipulation in Terraform Cloud workspaces, with the exception of rolling back to a previous state version, requires the use of Terraform CLI, using the same commands as would be used in a local workflow (terraform import, terraform taint, etc.). To manipulate state, you must configure the CLI integration and authenticate with a user token that has permission to read and write state versions for the relevant workspace. (More about permissions.)

Rolling Back to a Previous State

You can rollback to a previous, known good state version using the Terraform Cloud UI. Navigate to the state you want to rollback to and click the Advanced toggle button. This option requires that you have access to create new state and that you lock the workspace. It works by duplicating the state that you specify and making it the workspace's current state version. The workspace remains locked. To undo the rollback operation, rollback to the state version that was previously the latest state.

Accessing State from Other Workspaces

Terraform's built-in terraform_remote_state data source lets you share arbitrary information between configurations via root module outputs.

Terraform Cloud automatically manages API credentials for terraform_remote_state access during runs managed by Terraform Cloud. This means you do not usually need to include an API token in a terraform_remote_state data source's configuration.

Upgrading State

You can upgrade a workspace's state version to a new Terraform version without making any configuration changes. To upgrade, we recommend the following steps:

1. Run a speculative plan to test whether your configuration is compatible with the new Terraform version. You can run speculative plans with a Terraform version that is different than the one currently selected for the workspace.
2. Select Settings > General and select the desired new Terraform Version.
3. Click Actions > Start new run and then select Allow empty apply as the run type. An empty apply allows Terraform to apply a plan that produces no infrastructure changes. Terraform upgrades the state file version during the apply process.

Remote State Access Controls

Remote state access between workspaces is subject to access controls:

• Only workspaces within the same organization can access each other's state.
• The workspace whose state is being read must be configured to allow that access. State access permissions are configured on a workspace's general settings page. There are two ways a workspace can allow access:
  • Globally, to all workspaces within the same organization.
  • Selectively, to a list of specific approved workspaces.

By default, new workspaces in Terraform Cloud do not allow other workspaces to access their state. We recommend that you follow the principle of least privilege and only enable state access between workspaces that specifically need information from each other.

Data Source Configuration

To configure a tfe_outputs data source that references a Terraform Cloud workspace, specify the organization and workspace in the config argument.

You must still properly configure the tfe provider with a valid authentication token and correct permissions to Terraform Cloud.

data "tfe_outputs" "vpc" {
  config = {
    organization = "example_corp"
    workspaces = {
      name = "vpc-prod"
    }
  }
}

resource "aws_instance" "redis_server" {
  # Terraform 0.12 and later: use the "outputs.<OUTPUT NAME>" attribute
  subnet_id = data.tfe_outputs.vpc.outputs.subnet_id
}