Manage workspace state

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

State Usage in Terraform Runs

In remote runs, HCP Terraform 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.)

During an HCP Terraform run, Terraform incrementally creates intermediate state versions and marks them as finalized once it uploads the state content.

When a workspace is unlocked, HCP Terraform selects the latest state and sets it as the current state version, deletes all other intermediate state versions that were saved as recovery snapshots for the duration of the lock, and discards all pending intermediate state versions that were superseded by newer state versions.

State Versions

In addition to the current state, HCP Terraform 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.

Managed Resources Count

Note: A managed resources count for each organization is available in your organization's settings.

Your organization’s managed resource count helps you understand the number of infrastructure resources that HCP Terraform manages across all your workspaces.

HCP Terraform reads all the workspaces’ state files to determine the total number of managed resources. Each resource in the state equals one managed resource. HCP Terraform includes resources in modules and each resource instance created with the count or for_each meta-arguments. For example, "aws_instance" "servers" { count = 10 } creates ten separate managed resources in state. HCP Terraform does not include data sources in the count.

Examples - Managed Resources

The following Terraform state excerpt describes a random resource. HCP Terraform counts random as one managed resource because “mode”: “managed”.

"resources": [
{
      "mode": "managed",
      "type": "random_pet",
      "name": "random",
      "provider": "provider[\"registry.terraform.io/hashicorp/random\"]",
      "instances": [
        {
          "schema_version": 0,
          "attributes": {
            "id": "puma",
            "keepers": null,
            "length": 1,
            "prefix": null,
            "separator": "-"
          },
          "sensitive_attributes": []
        }
      ]
    }
]

A single resource configuration block can describe multiple resource instances with the count or for_each meta-arguments. Each of these instances counts as a managed resource.

The following example shows a Terraform state excerpt with 2 instances of a aws_subnet resource. HCP Terraform counts each instance of aws_subnet as a separate managed resource.

{
      "module": "module.vpc",
      "mode": "managed",
      "type": "aws_subnet",
      "name": "public",
      "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
      "instances": [
        {
          "index_key": 0,
          "schema_version": 1,
          "attributes": {
            "arn": "arn:aws:ec2:us-east-2:561656980159:subnet/subnet-024b05c4fba9c9733",
            "assign_ipv6_address_on_creation": false,
            "availability_zone": "us-east-2a",
            ##...
            "private_dns_hostname_type_on_launch": "ip-name",
            "tags": {
              "Name": "-public-us-east-2a"
            },
            "tags_all": {
              "Name": "-public-us-east-2a"
            },
            "timeouts": null,
            "vpc_id": "vpc-0f693f9721b61333b"
          },
          "sensitive_attributes": [],
          "private": "eyJlMmJmYjczMC1lY2FhLTExZTYtOGY4OC0zNDM2M2JjN2M0YzAiOnsiY3JlYXRlIjo2MDAwMDAwMDAwMDAsImRlbGV0ZSI6MTIwMDAwMDAwMDAwMH0sInNjaGVtYV92ZXJzaW9uIjoiMSJ9",
          "dependencies": [
            "data.aws_availability_zones.available",
            "module.vpc.aws_vpc.this",
            "module.vpc.aws_vpc_ipv4_cidr_block_association.this"
          ]
        },
        {
          "index_key": 1,
          "schema_version": 1,
          "attributes": {
            "arn": "arn:aws:ec2:us-east-2:561656980159:subnet/subnet-08924f16617e087b2",
            "assign_ipv6_address_on_creation": false,
            "availability_zone": "us-east-2b",
            ##...
            "private_dns_hostname_type_on_launch": "ip-name",
            "tags": {
              "Name": "-public-us-east-2b"
            },
            "tags_all": {
              "Name": "-public-us-east-2b"
            },
            "timeouts": null,
            "vpc_id": "vpc-0f693f9721b61333b"
          },
          "sensitive_attributes": [],
          "private": "eyJlMmJmYjczMC1lY2FhLTExZTYtOGY4OC0zNDM2M2JjN2M0YzAiOnsiY3JlYXRlIjo2MDAwMDAwMDAwMDAsImRlbGV0ZSI6MTIwMDAwMDAwMDAwMH0sInNjaGVtYV92ZXJzaW9uIjoiMSJ9",
          "dependencies": [
            "data.aws_availability_zones.available",
            "module.vpc.aws_vpc.this",
            "module.vpc.aws_vpc_ipv4_cidr_block_association.this"
          ]
        }
      ]
}

Example - Excluded Data Source

The following Terraform state excerpt describes a aws_availability_zones data source. HCP Terraform does not include aws_availability_zones in the managed resource count because ”mode”: “data”.

 "resources": [
    {
      "mode": "data",
      "type": "aws_availability_zones",
      "name": "available",
      "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
      "instances": [
        {
          "schema_version": 0,
          "attributes": {
            "all_availability_zones": null,
            "exclude_names": null,
            "exclude_zone_ids": null,
            "filter": null,
            "group_names": [
              "us-east-2"
            ],
            "id": "us-east-2",
            "names": [
              "us-east-2a",
              "us-east-2b",
              "us-east-2c"
            ],
            "state": null,
            "zone_ids": [
              "use2-az1",
              "use2-az2",
              "use2-az3"
            ]
          },
          "sensitive_attributes": []
        }
      ]
     }
   ]

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 HCP Terraform 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 HCP Terraform 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 HCP Terraform 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.

Note: You can rollback to any prior state, but you should use caution because replacing state improperly can result in orphaned or duplicated infrastructure resources. This feature is provided as a convenient alternative to manually downloading older state and using state manipulation commands in the CLI to push it to HCP Terraform.

Accessing State from Other Workspaces

Note: Provider-specific data sources are usually the most resilient way to share information between separate Terraform configurations. terraform_remote_state is more flexible, but we recommend using specialized data sources whenever it is convenient to do so.

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

HCP Terraform automatically manages API credentials for terraform_remote_state access during runs managed by HCP Terraform. 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:

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.
Select Settings > General and select the desired new Terraform Version.
Click + 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.

Note: If the desired Terraform version is incompatible with a workspace's existing state version, the run fails and HCP Terraform prompts you to run an apply with a compatible version first. Refer to the Terraform upgrade guides for details about upgrading between versions.

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 HCP Terraform 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.

Note: The default access permissions for new workspaces in HCP Terraform changed in April 2021. Workspaces created before this change defaulted to allowing global access within their organization. These workspaces can be changed to more restrictive access at any time on their general settings page. Terraform Enterprise administrators can choose whether new workspaces on their instances default to global access or selective access.

Data Source Configuration

To configure a tfe_outputs data source that references an HCP Terraform 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 HCP Terraform.

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
}

Note: Remote state access controls do not apply when using the tfe_outputs data source.