HashiConf 2025 Don't miss the live stream of HashiConf Day 2 happening now View live stream
Terraform
Terraform Home

Manage workspace state

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

API: See the State Versions API.

State usage in Terraform runs

In remote runs, HCP Terraform automatically configures the Terraform binary to use the state stored in the workspace. As a result, the Terraform configuration does not need an explicit backend configuration. If a backend configuration is present, it will be overridden.

Setting the workspace execution mode to Local lets you use the workspace's state by configuring the CLI integration. In this mode, you must present 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. Refer to Permissions overview for more information about setting permissions and workspace access.

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

HCP Terraform stores the current version of the state file, as well as historical state versions. You can use the historical state versions to analyze infrastructure changes over time.

To view a workspace's state versions, click the 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.

View managed resources

Your organization’s managed resource count helps you understand the number of infrastructure resources that HCP Terraform manages across all your workspaces. To review the number of managed resources for your organization, log into HCP Terraform and click Usage in the sidebar.

HCP Terraform reads all the workspaces’ state files to determine the total number of managed resources. When the mode attribute in a state file is set to managed, the resource counts toward the organizations managed resources.

Each resource block declared in a configuration appears in the state file and counts as 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. As a result, when the mode attribute in a state file is set to data, the resource doesn't count toward the organizations managed resources.

Example scenarios

Refer to the following examples to help you understand how HCP Terraform counts managed resources.

Standalone resource

In the following example, the Terraform state excerpt describes a random resource. HCP Terraform counts random as one managed resource because mode is set to 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": []
        }
      ]
    }
]

Multiple resources in a single resource block

A single resource block configuration 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 two instances of an 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"
          ]
        }
      ]
}

Data sources excluded from managed resource count

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 is set to 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": []
        }
      ]
     }
   ]

Update state to match your infrastructure

In some cases, you may need to modify your workspace state to match a configuration that diverged from the actual infrastructure. Divergence, also called drift, occurs when the infrastructure is modified outside the context of a normal Terraform run.

Depending on which version of Terraform your HCP Terraform workspace is configured to use, you can implement Terraform configuration language constructs, such as moved blocks and import blocks, or use HCP Terraform features, such as the Replace resources option, to update the state to match the actual infrastructure.

If the Terraform version you're using doesn't support these features, you may need to use Terraform CLI commands, such as terraform import and terraform taint, to modify the state stored in your HCP Terraform workspace. Note that the only state operation that doesn't required the CLI or language constructs is using the HCP Terraform UI to roll back to a previous state version.

To update state using the CLI, you must also configure the CLI integration and authenticate with a user token that has permission to read and write state versions for the relevant workspace. Refer to Permissions overview for more information about permissions.

Roll back to a previous state version

You can roll back to a previous, known good state version using the HCP Terraform UI. Navigate to the state you want to roll back 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, roll back to the state version that was previously the latest state.

You can roll back to any prior state, but you should make that you understand the changes between versions. Replacing state 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.

Upgrade state to a new Terraform version

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. Sign in to HCP Terraform or Terraform Enterprise and navigate to the workspace you want to upgrade.
  2. 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.
  3. Select Settings > General and select the desired new Terraform Version.
  4. 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.

If the Terraform version you want to use isn't compatible 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.

Access state from other workspaces

Configuring provider-specific data sources is usually the most resilient way to share information between separate Terraform configurations, but you can use Terraform's built-in terraform_remote_state data source to share arbitrary information between configurations through root module outputs when you aren't able to use the provider data sources.

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

Remote state access controls

You can configure workspaces to allow access to their state data. Refer Remote State Sharing for details. You can set the following access controls for remote state sharing:

  • Share with all workspaces in this organization: All other workspaces in the organization can access this workspace's state during runs.
  • Share with all workspaces in this project: All other workspaces in the same project can access this workspace's state during runs.
  • Share with specific workspaces: Lets you specify a list of workspaces in the organization that can access this workspace's state. The workspace selector is searchable. If you don't initially see a workspace you're looking for, type part of its name.

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.

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.

Edit this page on GitHub