terraform to access state from other workspaces page title Terraform State Workspaces HCP Terraform Workspaces have their own separate state data Learn how state is used and how Each HCP Terraform workspace has its own separate state data used for runs within that workspace Terraform State in HCP Terraform

Answer:
---
page_title: Terraform State - Workspaces - HCP Terraform
description: >-
  Workspaces have their own separate state data. Learn how state is used and how
  to access state from other workspaces.
---

# Terraform State in HCP Terraform

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

-> **API:** See the [State Versions API](/terraform/cloud-docs/api-docs/state-versions).

## State Usage in Terraform Runs

In [remote runs](/terraform/cloud-docs/run/remote-operations), 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](/terraform/cli/cloud) 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.](/terraform/cloud-docs/users-teams-organizations/permissions))

<!-- BEGIN: TFC:only name:intermediate-state -->

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.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

<!-- END: TFC:only name:intermediate-state -->

## 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.

<!-- BEGIN: TFC:only name:managed-resources -->
## 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](/terraform/language/resources/syntax) 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](/terraform/language/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”`.

```json
"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`](/terraform/language/meta-arguments/count) or [`for_each`](/terraform/language/meta-arguments/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.

```json
{
      "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”`.

```json
 "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": []
        }
      ]
     }
   ]
```
<!-- END: TFC:only name:managed-resources -->

## 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](/terraform/language/modules/develop/refactoring), [`import` blocks](/terraform/language/import), and the [`replace` option](/terraform/cloud-docs/run/modes-and-options#replacing-selected-resources) 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](#rolling-back-to-a-previous-state), 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](/terraform/cli/cloud) and authenticate with a user token that has permission to read and write state versions for the relevant workspace. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/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.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

## Accessing State from Other Workspaces

-> **Note:** Provider-specific [data sources](/terraform/language/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](/terraform/language/state/remote-state-data) lets you share arbitrary information between configurations via root module [outputs](/terraform/language/values/outputs).

HCP Terraform automatically manages API credentials for `terraform_remote_state` access during [runs managed by HCP Terraform](/terraform/cloud-docs/run/remote-operations#remote-operations). 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](/terraform/cloud-docs/run/ui#testing-terraform-upgrades-with-speculative-plans) 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.
1.  Select **Settings > General** and select the desired new **Terraform Version**.
1.  Click **+ New run** and then select **Allow empty apply** as the run type. An [empty apply](/terraform/cloud-docs/run/modes-and-options#allow-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](/terraform/language/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](/terraform/cloud-docs/workspaces/settings). 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/cloud-docs/workspaces/settings). 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.

```hcl
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.

page title  Terraform State   Workspaces   HCP Terraform description       Workspaces have their own separate state data  Learn how state is used and how   to access state from other workspaces         Terraform State in HCP Terraform  Each HCP Terraform workspace has its own separate state data  used for runs within that workspace        API    See the  State Versions API   terraform cloud docs api docs state versions       State Usage in Terraform Runs  In  remote runs   terraform cloud docs run remote operations   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   terraform cli cloud  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    terraform cloud docs users teams organizations permissions         BEGIN  TFC only name intermediate state      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    permissions citation    intentionally unused   keep for maintainers       END  TFC only name intermediate state         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        BEGIN  TFC only name managed resources        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   terraform language resources syntax  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   terraform language 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        json  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    terraform language meta arguments count  or   for each    terraform language meta arguments 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      json          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        json   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                                             END  TFC only name managed resources         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   terraform language modules develop refactoring     import  blocks   terraform language import   and the   replace  option   terraform cloud docs run modes and options replacing selected resources  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   rolling back to a previous state   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   terraform cli cloud  and authenticate with a user token that has permission to read and write state versions for the relevant workspace    More about permissions    terraform cloud docs users teams organizations 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    permissions citation    intentionally unused   keep for maintainers     Accessing State from Other Workspaces       Note    Provider specific  data sources   terraform language 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   terraform language state remote state data  lets you share arbitrary information between configurations via root module  outputs   terraform language values outputs    HCP Terraform automatically manages API credentials for  terraform remote state  access during  runs managed by HCP Terraform   terraform cloud docs run remote operations remote operations   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   terraform cloud docs run ui testing terraform upgrades with speculative plans  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  1   Select   Settings   General   and select the desired new   Terraform Version    1   Click     New run   and then select   Allow empty apply   as the run type  An  empty apply   terraform cloud docs run modes and options allow 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   terraform language 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   terraform cloud docs workspaces settings   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 cloud docs workspaces settings   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      hcl 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


terraform You can change a workspace s settings after creation Workspace settings are separated into several pages page title Settings Workspaces HCP Terraform settings for notifications permissions and more Workspaces organize infrastructure Find documentation about workspace Workspace Settings

Answer:
---
page_title: Settings - Workspaces - HCP Terraform
description: >-
  Workspaces organize infrastructure. Find documentation about workspace
  settings for notifications, permissions, and more.
---

# Workspace Settings

You can change a workspace’s settings after creation. Workspace settings are separated into several pages.

- [General](#general): Settings that determine how the workspace functions, including its name, description, associated project, Terraform version, and execution mode.
- [Health](/terraform/cloud-docs/workspaces/health): Settings that let you configure health assessments, including drift detection and continuous validation.
- [Locking](#locking): Locking a workspace temporarily prevents new plans and applies.
- [Notifications](#notifications): Settings that let you configure run notifications.
- [Policies](#policies): Settings that let you toggle between Sentinel policy evaluation experiences.
- [Run Triggers](#run-triggers): Settings that let you configure run triggers. Run triggers allow runs to queue automatically in your workspace when runs in other workspaces are successful.
- [SSH Key](#ssh-key): Set a private SSH key for downloading Terraform modules from Git-based module sources.
- [Team Access](#team-access): Settings that let you manage which teams can view the workspace and use it to provision infrastructure.
- [Version Control](#version-control): Manage the workspace’s VCS integration.
- [Destruction and Deletion](#destruction-and-deletion): Remove a workspace and the infrastructure it manages.

Changing settings requires admin access to the relevant workspace. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))

[permissions-citation]: #intentionally-unused---keep-for-maintainers

-> **API:** See the [Update a Workspace endpoint](/terraform/cloud-docs/api-docs/workspaces#update-a-workspace) (`PATCH /organizations/:organization_name/workspaces/:name`).

## General

General settings let you change a workspace's name, description, the project it belongs to, and details about how Terraform runs operate. After changing these settings, click **Save settings** at the bottom of the page.

### ID

Every workspace has a unique ID that you cannot change. You may need to reference the workspace's ID when using the [HCP Terraform API](/terraform/cloud-docs/api-docs).

Click the icon beside the ID to copy it to your clipboard.

### Name

The display name of the workspace.

!> **Warning:** Some API calls refer to a workspace by its name, so changing the name may break existing integrations.

### Project

The [project](/terraform/cloud-docs/projects) that this workspace belongs to. Changing the workspace's project can change the read and write permissions for the workspace and which users can access it.

To move a workspace, you must have the "Manage all Projects" organization permission or explicit team admin privileges on both the source and destination projects. Remember that moving a workspace to another project may affect user visibility for that project's workspaces. Refer to [Project Permissions](/terraform/cloud-docs/users-teams-organizations/permissions#project-permissions) for details on workspace access.

### Description (Optional)

Enter a brief description of the workspace's purpose or types of infrastructure.

### Execution Mode

Whether to use HCP Terraform as the Terraform execution platform for this workspace.

By default, HCP Terraform uses an organization's [default execution mode](/terraform/cloud-docs/users-teams-organizations/organizations#organization-settings) to choose the execution platform for a workspace. Alternatively, you can instead choose a custom execution mode for a workspace.

Specifying the "Remote" execution mode instructs HCP Terraform to perform Terraform runs on its own disposable virtual machines. This provides a consistent and reliable run environment and enables advanced features like Sentinel policy enforcement, cost estimation, notifications, version control integration, and more.

To disable remote execution for a workspace, change its execution mode to "Local". This mode lets you perform Terraform runs locally with the [CLI-driven run workflow](/terraform/cloud-docs/run/cli). The workspace will store state, which Terraform can access with the [CLI integration](/terraform/cli/cloud). HCP Terraform does not evaluate workspace variables or variable sets in local execution mode.

If you instead need to allow HCP Terraform to communicate with isolated, private, or on-premises infrastructure, consider using [HCP Terraform agents](/terraform/cloud-docs/agents). By deploying a lightweight agent, you can establish a simple connection between your environment and HCP Terraform.

Changing your workspace's execution mode after a run has already been planned will cause the run to error when it is applied.

To minimize the number of runs that error when changing your workspace's execution mode, you should:

1. Disable [auto-apply](/terraform/cloud-docs/workspaces/settings#auto-apply) if you have it enabled.
1. Complete any runs that are no longer in the [pending stage](/terraform/cloud-docs/run/states#the-pending-stage).
1. [Lock](/terraform/cloud-docs/workspaces/settings#locking) your workspace to prevent any new runs.
1. Change the execution mode.
1. Enable [auto-apply](/terraform/cloud-docs/workspaces/settings#auto-apply), if you had it enabled before changing your execution mode.
1. [Unlock](/terraform/cloud-docs/workspaces/settings#locking) your workspace.

### Auto-apply

Whether or not HCP Terraform should automatically apply a successful Terraform plan. If you choose manual apply, an operator must confirm a successful plan and choose to apply it.

The main auto-apply setting affects runs created by the HCP Terraform user interface, API, CLI, and version control webhooks. HCP Terraform also has a separate setting for runs created by [run triggers](/terraform/cloud-docs/workspaces/settings/run-triggers) from another workspace.

Auto-apply has the following exception:

- Plans queued by users without permission to apply runs for the workspace must be approved by a user who does have permission. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))

[permissions-citation]: #intentionally-unused---keep-for-maintainers

### Terraform Version

The Terraform version to use for all operations in the workspace. The default value is whichever release was current when HCP Terraform created the workspace. You can also update a workspace's Terraform version to an exact version or a valid [version constraint](/terraform/language/expressions/version-constraints).

> **Hands-on:** Try the [Upgrade Terraform Version in HCP Terraform](/terraform/tutorials/cloud/cloud-versions) tutorial.

-> **API:** You can specify a Terraform version when you [create a workspace](/terraform/cloud-docs/api-docs/workspaces#create-a-workspace) with the API.

### Terraform Working Directory

The directory where Terraform will execute, specified as a relative path from the root of the configuration directory. Defaults to the root of the configuration directory.

HCP Terraform will change to this directory before starting a Terraform run, and will report an error if the directory does not exist.

Setting a working directory creates a default filter for automatic run triggering, and sometimes causes CLI-driven runs to upload additional configuration content.

#### Default Run Trigger Filtering

In VCS-backed workspaces that specify a working directory, HCP Terraform assumes that only changes within that working directory should trigger a run. You can override this behavior with the [Automatic Run Triggering](/terraform/cloud-docs/workspaces/settings/vcs#automatic-run-triggering) settings.

#### Parent Directory Uploads

If a working directory is configured, HCP Terraform always expects the complete shared configuration directory to be available, since the configuration might use local modules from outside its working directory.

In [runs triggered by VCS commits](/terraform/cloud-docs/run/ui), this is automatic. In [CLI-driven runs](/terraform/cloud-docs/run/cli), Terraform's CLI sometimes uploads additional content:

- When the local working directory _does not match_ the name of the configured working directory, Terraform assumes it is the root of the configuration directory, and uploads only the local working directory.
- When the local working directory _matches_ the name of the configured working directory, Terraform uploads one or more parents of the local working directory, according to the depth of the configured working directory. (For example, a working directory of `production` is only one level deep, so Terraform would upload the immediate parent directory. `consul/production` is two levels deep, so Terraform would upload the parent and grandparent directories.)

If you use the working directory setting, always run Terraform from a complete copy of the configuration directory. Moving one subdirectory to a new location can result in unexpected content uploads.

### Remote State Sharing

Which other workspaces within the organization can access the state of the workspace during [runs managed by HCP Terraform](/terraform/cloud-docs/run/remote-operations#remote-operations). The [`terraform_remote_state` data source](/terraform/language/state/remote-state-data) relies on state sharing to access workspace outputs.

- If "Share state globally" is enabled, all other workspaces within the organization can access this workspace's state during runs.
- If global sharing is turned off, you can specify a list of workspaces within the organization that can access this workspace's state; no other workspaces will be allowed.

  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. To configure remote state sharing, a user must have read access for the destination workspace. If a user does not have access to the destination workspace due to scoped project or workspace permissions, they will not have complete visibility into the list of other workspace that can access its state.

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

### User Interface

Select the user experience for displaying plan and apply details.

The default experience is _Structured Run Output_, which displays your plan and apply results in a human-readable format. This includes nodes that you can expand to view details about each resource and any configured output.

The Console UI experience is the traditional Terraform experience, where live text logging is streamed in real time to the UI. This experience most closely emulates the CLI output.

~> **Note:** Your workspace must be configured to use a Terraform version of 1.0.5 or higher for the Structured Run Output experience to be fully supported. Workspaces running versions from 0.15.2 may see partial functionality. Workspaces running versions below 0.15.2 will default to the "Console UI" experience regardless of the User Interface setting.

## Locking

~> **Important:** Unlike other settings, locks can also be managed by users with permission to lock and unlock the workspace. ([More about permissions.](/terraform/cloud-docs/users-teams-organizations/permissions))

[permissions-citation]: #intentionally-unused---keep-for-maintainers

If you need to prevent Terraform runs for any reason, you can lock a workspace. This prevents all applies (and many kinds of plans) from proceeding, and affects runs created via UI, CLI, API, and automated systems. To enable runs again, a user must unlock the workspace.

Two kinds of run operations can ignore workspace locking because they cannot affect resources or state and do not attempt to lock the workspace themselves:

- Plan-only runs.
- The planning stages of [saved plan runs](/terraform/cloud-docs/run/modes-and-options.mdx#saved-plans). You can only _apply_ a saved plan if the workspace is unlocked, and applying that plan locks the workspace as usual. Terraform Enterprise does not yet support this workflow.

Locking a workspace also restricts state uploads. In order to upload state, the workspace must be locked by the user who is uploading state.

Users with permission to lock and unlock a workspace can't unlock a workspace which was locked by another user. Users with admin access to a workspace can force unlock a workspace even if another user has locked it.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

Locks are managed with a single "Lock/Unlock/Force unlock `<WORKSPACE NAME>`" button. HCP Terraform asks for confirmation when unlocking.

You can also manage the workspace's lock from the **Actions** menu.

## Notifications

The "Notifications" page allows HCP Terraform to send webhooks to external services whenever specific run events occur in a workspace.

See [Run Notifications](/terraform/cloud-docs/workspaces/settings/notifications) for detailed information about configuring notifications.

## Policies

HCP Terraform offers two experiences for Sentinel policy evaluations. On the "Policies" page, you can adjust your **Sentinel Experience** settings to your preferred experience. By default, HCP Terraform enables the newest policy evaluation experience.

To toggle between the two Sentinel policy evaluation experiences, click the **Enable the new Sentinel policy experience** toggle under the **Sentinel Experience** heading. HCP Terraform persists your changes automatically. If HCP Terraform is performing a run on a different page, you must refresh that page to see changes to your policy evaluation experience.

## Run Triggers

The "Run Triggers" page configures connections between a workspace and one or more source workspaces. These connections, called "run triggers", allow runs to queue automatically in a workspace on successful apply of runs in any of the source workspaces.

See [Run Triggers](/terraform/cloud-docs/workspaces/settings/run-triggers) for detailed information about configuring run triggers.

## SSH Key

If a workspace's configuration uses [Git-based module sources](/terraform/language/modules/sources) to reference Terraform modules in private Git repositories, Terraform needs an SSH key to clone those repositories. The "SSH Key" page lets you choose which key it should use.

See [Using SSH Keys for Cloning Modules](/terraform/cloud-docs/workspaces/settings/ssh-keys) for detailed information about this page.

## Team Access

The "Team Access" page configures which teams can perform which actions on a workspace.

See [Managing Access to Workspaces](/terraform/cloud-docs/workspaces/settings/access) for detailed information.

## Version Control

The "Version Control" page configures an optional VCS repository that contains the workspace's Terraform configuration. Version control integration is only relevant for workspaces with [remote execution](#execution-mode) enabled.

See [VCS Connections](/terraform/cloud-docs/workspaces/settings/vcs) for detailed information about this page.

## Destruction and Deletion

The **Destruction and Deletion** page allows [admin users](/terraform/cloud-docs/users-teams-organizations/permissions) to delete a workspace's managed infrastructure or delete the workspace itself.

For details, refer to [Destruction and Deletion](/terraform/cloud-docs/workspaces/settings/deletion) for detailed information about this page.

page title  Settings   Workspaces   HCP Terraform description       Workspaces organize infrastructure  Find documentation about workspace   settings for notifications  permissions  and more         Workspace Settings  You can change a workspace s settings after creation  Workspace settings are separated into several pages      General   general   Settings that determine how the workspace functions  including its name  description  associated project  Terraform version  and execution mode     Health   terraform cloud docs workspaces health   Settings that let you configure health assessments  including drift detection and continuous validation     Locking   locking   Locking a workspace temporarily prevents new plans and applies     Notifications   notifications   Settings that let you configure run notifications     Policies   policies   Settings that let you toggle between Sentinel policy evaluation experiences     Run Triggers   run triggers   Settings that let you configure run triggers  Run triggers allow runs to queue automatically in your workspace when runs in other workspaces are successful     SSH Key   ssh key   Set a private SSH key for downloading Terraform modules from Git based module sources     Team Access   team access   Settings that let you manage which teams can view the workspace and use it to provision infrastructure     Version Control   version control   Manage the workspace s VCS integration     Destruction and Deletion   destruction and deletion   Remove a workspace and the infrastructure it manages   Changing settings requires admin access to the relevant workspace    More about permissions    terraform cloud docs users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers       API    See the  Update a Workspace endpoint   terraform cloud docs api docs workspaces update a workspace    PATCH  organizations  organization name workspaces  name        General  General settings let you change a workspace s name  description  the project it belongs to  and details about how Terraform runs operate  After changing these settings  click   Save settings   at the bottom of the page       ID  Every workspace has a unique ID that you cannot change  You may need to reference the workspace s ID when using the  HCP Terraform API   terraform cloud docs api docs    Click the icon beside the ID to copy it to your clipboard       Name  The display name of the workspace        Warning    Some API calls refer to a workspace by its name  so changing the name may break existing integrations       Project  The  project   terraform cloud docs projects  that this workspace belongs to  Changing the workspace s project can change the read and write permissions for the workspace and which users can access it    To move a workspace  you must have the  Manage all Projects  organization permission or explicit team admin privileges on both the source and destination projects  Remember that moving a workspace to another project may affect user visibility for that project s workspaces  Refer to  Project Permissions   terraform cloud docs users teams organizations permissions project permissions  for details on workspace access       Description  Optional   Enter a brief description of the workspace s purpose or types of infrastructure       Execution Mode  Whether to use HCP Terraform as the Terraform execution platform for this workspace   By default  HCP Terraform uses an organization s  default execution mode   terraform cloud docs users teams organizations organizations organization settings  to choose the execution platform for a workspace  Alternatively  you can instead choose a custom execution mode for a workspace   Specifying the  Remote  execution mode instructs HCP Terraform to perform Terraform runs on its own disposable virtual machines  This provides a consistent and reliable run environment and enables advanced features like Sentinel policy enforcement  cost estimation  notifications  version control integration  and more   To disable remote execution for a workspace  change its execution mode to  Local   This mode lets you perform Terraform runs locally with the  CLI driven run workflow   terraform cloud docs run cli   The workspace will store state  which Terraform can access with the  CLI integration   terraform cli cloud   HCP Terraform does not evaluate workspace variables or variable sets in local execution mode   If you instead need to allow HCP Terraform to communicate with isolated  private  or on premises infrastructure  consider using  HCP Terraform agents   terraform cloud docs agents   By deploying a lightweight agent  you can establish a simple connection between your environment and HCP Terraform   Changing your workspace s execution mode after a run has already been planned will cause the run to error when it is applied   To minimize the number of runs that error when changing your workspace s execution mode  you should   1  Disable  auto apply   terraform cloud docs workspaces settings auto apply  if you have it enabled  1  Complete any runs that are no longer in the  pending stage   terraform cloud docs run states the pending stage   1   Lock   terraform cloud docs workspaces settings locking  your workspace to prevent any new runs  1  Change the execution mode  1  Enable  auto apply   terraform cloud docs workspaces settings auto apply   if you had it enabled before changing your execution mode  1   Unlock   terraform cloud docs workspaces settings locking  your workspace    a id  apply method    a   a id  auto apply and manual apply    a       Auto apply  Whether or not HCP Terraform should automatically apply a successful Terraform plan  If you choose manual apply  an operator must confirm a successful plan and choose to apply it   The main auto apply setting affects runs created by the HCP Terraform user interface  API  CLI  and version control webhooks  HCP Terraform also has a separate setting for runs created by  run triggers   terraform cloud docs workspaces settings run triggers  from another workspace   Auto apply has the following exception     Plans queued by users without permission to apply runs for the workspace must be approved by a user who does have permission    More about permissions    terraform cloud docs users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers      Terraform Version  The Terraform version to use for all operations in the workspace  The default value is whichever release was current when HCP Terraform created the workspace  You can also update a workspace s Terraform version to an exact version or a valid  version constraint   terraform language expressions version constraints        Hands on    Try the  Upgrade Terraform Version in HCP Terraform   terraform tutorials cloud cloud versions  tutorial        API    You can specify a Terraform version when you  create a workspace   terraform cloud docs api docs workspaces create a workspace  with the API       Terraform Working Directory  The directory where Terraform will execute  specified as a relative path from the root of the configuration directory  Defaults to the root of the configuration directory   HCP Terraform will change to this directory before starting a Terraform run  and will report an error if the directory does not exist   Setting a working directory creates a default filter for automatic run triggering  and sometimes causes CLI driven runs to upload additional configuration content        Default Run Trigger Filtering  In VCS backed workspaces that specify a working directory  HCP Terraform assumes that only changes within that working directory should trigger a run  You can override this behavior with the  Automatic Run Triggering   terraform cloud docs workspaces settings vcs automatic run triggering  settings        Parent Directory Uploads  If a working directory is configured  HCP Terraform always expects the complete shared configuration directory to be available  since the configuration might use local modules from outside its working directory   In  runs triggered by VCS commits   terraform cloud docs run ui   this is automatic  In  CLI driven runs   terraform cloud docs run cli   Terraform s CLI sometimes uploads additional content     When the local working directory  does not match  the name of the configured working directory  Terraform assumes it is the root of the configuration directory  and uploads only the local working directory    When the local working directory  matches  the name of the configured working directory  Terraform uploads one or more parents of the local working directory  according to the depth of the configured working directory   For example  a working directory of  production  is only one level deep  so Terraform would upload the immediate parent directory   consul production  is two levels deep  so Terraform would upload the parent and grandparent directories    If you use the working directory setting  always run Terraform from a complete copy of the configuration directory  Moving one subdirectory to a new location can result in unexpected content uploads       Remote State Sharing  Which other workspaces within the organization can access the state of the workspace during  runs managed by HCP Terraform   terraform cloud docs run remote operations remote operations   The   terraform remote state  data source   terraform language state remote state data  relies on state sharing to access workspace outputs     If  Share state globally  is enabled  all other workspaces within the organization can access this workspace s state during runs    If global sharing is turned off  you can specify a list of workspaces within the organization that can access this workspace s state  no other workspaces will be allowed     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  To configure remote state sharing  a user must have read access for the destination workspace  If a user does not have access to the destination workspace due to scoped project or workspace permissions  they will not have complete visibility into the list of other workspace that can access its state        Note    The default access permissions for new workspaces in HCP Terraform changed in April 2021  Workspaces created before this change default to allowing global access within their organization  These workspaces can be changed to more restrictive access at any time  Terraform Enterprise administrators can choose whether new workspaces on their instances default to global access or selective access       User Interface  Select the user experience for displaying plan and apply details   The default experience is  Structured Run Output   which displays your plan and apply results in a human readable format  This includes nodes that you can expand to view details about each resource and any configured output   The Console UI experience is the traditional Terraform experience  where live text logging is streamed in real time to the UI  This experience most closely emulates the CLI output        Note    Your workspace must be configured to use a Terraform version of 1 0 5 or higher for the Structured Run Output experience to be fully supported  Workspaces running versions from 0 15 2 may see partial functionality  Workspaces running versions below 0 15 2 will default to the  Console UI  experience regardless of the User Interface setting      Locking       Important    Unlike other settings  locks can also be managed by users with permission to lock and unlock the workspace    More about permissions    terraform cloud docs users teams organizations permissions     permissions citation    intentionally unused   keep for maintainers  If you need to prevent Terraform runs for any reason  you can lock a workspace  This prevents all applies  and many kinds of plans  from proceeding  and affects runs created via UI  CLI  API  and automated systems  To enable runs again  a user must unlock the workspace   Two kinds of run operations can ignore workspace locking because they cannot affect resources or state and do not attempt to lock the workspace themselves     Plan only runs    The planning stages of  saved plan runs   terraform cloud docs run modes and options mdx saved plans   You can only  apply  a saved plan if the workspace is unlocked  and applying that plan locks the workspace as usual  Terraform Enterprise does not yet support this workflow   Locking a workspace also restricts state uploads  In order to upload state  the workspace must be locked by the user who is uploading state   Users with permission to lock and unlock a workspace can t unlock a workspace which was locked by another user  Users with admin access to a workspace can force unlock a workspace even if another user has locked it    permissions citation    intentionally unused   keep for maintainers  Locks are managed with a single  Lock Unlock Force unlock   WORKSPACE NAME    button  HCP Terraform asks for confirmation when unlocking   You can also manage the workspace s lock from the   Actions   menu      Notifications  The  Notifications  page allows HCP Terraform to send webhooks to external services whenever specific run events occur in a workspace   See  Run Notifications   terraform cloud docs workspaces settings notifications  for detailed information about configuring notifications      Policies  HCP Terraform offers two experiences for Sentinel policy evaluations  On the  Policies  page  you can adjust your   Sentinel Experience   settings to your preferred experience  By default  HCP Terraform enables the newest policy evaluation experience   To toggle between the two Sentinel policy evaluation experiences  click the   Enable the new Sentinel policy experience   toggle under the   Sentinel Experience   heading  HCP Terraform persists your changes automatically  If HCP Terraform is performing a run on a different page  you must refresh that page to see changes to your policy evaluation experience      Run Triggers  The  Run Triggers  page configures connections between a workspace and one or more source workspaces  These connections  called  run triggers   allow runs to queue automatically in a workspace on successful apply of runs in any of the source workspaces   See  Run Triggers   terraform cloud docs workspaces settings run triggers  for detailed information about configuring run triggers      SSH Key  If a workspace s configuration uses  Git based module sources   terraform language modules sources  to reference Terraform modules in private Git repositories  Terraform needs an SSH key to clone those repositories  The  SSH Key  page lets you choose which key it should use   See  Using SSH Keys for Cloning Modules   terraform cloud docs workspaces settings ssh keys  for detailed information about this page      Team Access  The  Team Access  page configures which teams can perform which actions on a workspace   See  Managing Access to Workspaces   terraform cloud docs workspaces settings access  for detailed information      Version Control  The  Version Control  page configures an optional VCS repository that contains the workspace s Terraform configuration  Version control integration is only relevant for workspaces with  remote execution   execution mode  enabled   See  VCS Connections   terraform cloud docs workspaces settings vcs  for detailed information about this page      Destruction and Deletion  The   Destruction and Deletion   page allows  admin users   terraform cloud docs users teams organizations permissions  to delete a workspace s managed infrastructure or delete the workspace itself   For details  refer to  Destruction and Deletion   terraform cloud docs workspaces settings deletion  for detailed information about this page


terraform page title Destruction and Deletion Workspaces HCP Terraform HCP Terraform workspaces have two primary delete actions Learn about destroying infrastructure and deleting workspaces in HCP Terraform Destruction and Deletion

Answer:
---
page_title: Destruction and Deletion - Workspaces - HCP Terraform
description: |-
  Learn about destroying infrastructure and deleting workspaces in HCP Terraform.
---

# Destruction and Deletion

HCP Terraform workspaces have two primary delete actions:

- [Destroying infrastructure](#destroy-infrastructure) deletes resources managed by the HCP Terraform workspace by triggering a destroy run.
- [Deleting a workspace](#delete-workspaces) deletes the workspace itself without triggering a destroy run.

In general, you should perform both actions in the above order when destroying a workspace to ensure resource cleanup for all of a workspace's managed infrastructure.

## Destroy Infrastructure

Destroy plans delete the infrastructure managed by a workspace. We recommend destroying the infrastructure managed by a workspace _before_ deleting the workspace itself. Otherwise, the unmanaged infrastructure resources will continue to exist but will become unmanaged, and you must go into your infrastructure providers to delete the resources manually.

Before queuing a destroy plan, enable the **Allow destroy plans** toggle setting on this page.

### Automatically Destroy

@include 'tfc-package-callouts/ephemeral-workspaces.mdx'

Configuring automatic infrastructure destruction for a workspace requires [admin permissions](/terraform/cloud-docs/users-teams-organizations/permissions#workspace-admins) for that workspace.

There are two main ways to automatically destroy a workspace's resources:
* Schedule a run to destroy all resources in a workspace at a specific date and time.
* Configure HCP Terraform to destroy a workspace's infrastructure after a period of workspace inactivity.

Workspaces can inherit auto-destroy settings from their project. Refer to [managing projects](/terraform/cloud-docs/projects/manage#automatically-destroy-inactive-workspaces) for more information. You can configure an individual workspace's auto-destroy settings to override the project's configuration.

You can reduce your spending on infrastructure by automatically destroying temporary resources like development environments.

After HCP Terraform performs an auto-destroy run, it unsets the `auto-destroy-at` field on the workspace. If you continue using the workspace, you can schedule another future auto-destroy run to remove any new resources.

!> **Note:** Automatic destroy plans _do not_ prompt you for apply approval in the HCP Terraform user interface. We recommend only using this setting for development environments.

You can schedule an auto-destroy run using the HCP Terraform web user interface, or the [workspace API](/terraform/cloud-docs/api-docs/workspaces).

You can also schedule [notifications](/terraform/cloud-docs/workspaces/settings/notifications) to alert you 12 and 24 hours before an auto-destroy run, and to report auto-destroy run results.

#### Destroy at a specific day and time

To schedule an auto-destroy run at a specific time in HCP Terraform:
1. Navigate to the workspace's **Settings** > **Destruction and Deletion** page.
1. Under **Automatically destroy**, click **Set up auto-destroy**.
1. Enter the desired date and time. HCP Terraform defaults to your local time zone for scheduling and displays how long until the scheduled operation.
1. Click **Confirm auto-destroy**.

To cancel a scheduled auto-destroy run in HCP Terraform:
1. Navigate to the workspace's **Settings** > **Destruction and Deletion** page.
1. Under **Automatically destroy**, click **Edit** next to your scheduled run's details.
1. Click **Remove**.

#### Destroy if a workspace is inactive

You can configure HCP Terraform to automatically destroy a workspace's infrastructure after a period of inactivity.
A workspace is _inactive_ if the workspace's state has not changed within your designated time period.

!> **Caution:** As opposed to configuring an auto-destroy run for a specific date and time, this setting _persists_ after queueing auto-destroy runs.

If you configure a workspace to auto-destroy its infrastructure when inactive, any run that updates Terraform state further delays the scheduled auto-destroy time by the length of your designated timeframe.

To schedule an auto-destroy run after a period of workspace inactivity:
1. Navigate to the workspace's **Settings** > **Destruction and Deletion** page.
1. Under **Automatically destroy**, click **Set up auto-destroy**.
1. Click the **Destroy if inactive** toggle.
1. Select or customize a desired timeframe of inactivity.
1. Click **Confirm auto-destroy**.

When configured for the first time, the auto-destroy duration setting displays the scheduled date and time that HCP Terraform will perform the auto-destroy run.
Subsequent auto-destroy runs and Terraform runs that update state both update the next scheduled auto-destroy date.

After HCP Terraform completes a manual or automatic destroy run, it waits until further state updates to schedule a new auto-destroy run.

To remove your workspace's auto-destroy based on inactivity:
1. Navigate to the workspace's **Settings** > **Destruction and Deletion** page.
1. Under **Auto-destroy settings**, click **Edit** to change the auto-destroy settings.
1. Click **Remove**.

## Delete Workspace

Terraform does not automatically destroy managed infrastructure when you delete a workspace.

After you delete the workspace and its state file, Terraform can _no longer track or manage_ that infrastructure. You must manually delete or [import](/terraform/cli/commands/import) any remaining resources into another Terraform workspace.

By default, [workspace administrators](/terraform/cloud-docs/users-teams-organizations/permissions#workspace-admins) can only delete unlocked workspaces that are not managing any infrastructure. Organization owners can force delete a workspace to override these protections. Organization owners can also configure the [organization's settings](/terraform/cloud-docs/users-teams-organizations/organizations#general) to let workspace administrators force delete their own workspaces.

## Data Retention Policies

<EnterpriseAlert>
Data retention policies are exclusive to Terraform Enterprise, and not available in HCP Terraform. Learn more about Terraform Enterprise.
</EnterpriseAlert>

Define configurable data retention policies for workspaces to help reduce object storage consumption. You can define a policy that allows Terraform to _soft delete_ the backing data associated with configuration versions and state versions. Soft deleting refers to marking a data object for garbage collection so that Terraform can automatically delete the object after a set number of days.

Once an object is soft deleted, any attempts to read the object will fail. Until the garbage collection grace period elapses, you can still restore an object using the APIs described in the [configuration version documentation](/terraform/enterprise/api-docs/configuration-versions) and [state version documentation](/terraform/enterprise/api-docs/state-versions). After the garbage collection grace period elapses, Terraform permanently deletes the archivist storage.

The [organization policy](/terraform/enterprise/users-teams-organizations/organizations#destruction-and-deletion) is the default policy applied to workspaces, but members of individual workspaces can override the policy for their workspaces.

The workspace policy always overrides the organization policy. A workspace admin can set or override the following data retention policies:

- **Organization default policy**
- **Do not auto-delete**
- **Auto-delete data**

Setting the data retention policy to **Organization default policy** disables the other data retention policy settings.

page title  Destruction and Deletion   Workspaces   HCP Terraform description       Learn about destroying infrastructure and deleting workspaces in HCP Terraform         Destruction and Deletion  HCP Terraform workspaces have two primary delete actions      Destroying infrastructure   destroy infrastructure  deletes resources managed by the HCP Terraform workspace by triggering a destroy run     Deleting a workspace   delete workspaces  deletes the workspace itself without triggering a destroy run   In general  you should perform both actions in the above order when destroying a workspace to ensure resource cleanup for all of a workspace s managed infrastructure      Destroy Infrastructure  Destroy plans delete the infrastructure managed by a workspace  We recommend destroying the infrastructure managed by a workspace  before  deleting the workspace itself  Otherwise  the unmanaged infrastructure resources will continue to exist but will become unmanaged  and you must go into your infrastructure providers to delete the resources manually   Before queuing a destroy plan  enable the   Allow destroy plans   toggle setting on this page       Automatically Destroy       BEGIN  TFC only name pnp callout      include  tfc package callouts ephemeral workspaces mdx       END  TFC only name pnp callout      Configuring automatic infrastructure destruction for a workspace requires  admin permissions   terraform cloud docs users teams organizations permissions workspace admins  for that workspace   There are two main ways to automatically destroy a workspace s resources    Schedule a run to destroy all resources in a workspace at a specific date and time    Configure HCP Terraform to destroy a workspace s infrastructure after a period of workspace inactivity   Workspaces can inherit auto destroy settings from their project  Refer to  managing projects   terraform cloud docs projects manage automatically destroy inactive workspaces  for more information  You can configure an individual workspace s auto destroy settings to override the project s configuration   You can reduce your spending on infrastructure by automatically destroying temporary resources like development environments   After HCP Terraform performs an auto destroy run  it unsets the  auto destroy at  field on the workspace  If you continue using the workspace  you can schedule another future auto destroy run to remove any new resources         Note    Automatic destroy plans  do not  prompt you for apply approval in the HCP Terraform user interface  We recommend only using this setting for development environments   You can schedule an auto destroy run using the HCP Terraform web user interface  or the  workspace API   terraform cloud docs api docs workspaces    You can also schedule  notifications   terraform cloud docs workspaces settings notifications  to alert you 12 and 24 hours before an auto destroy run  and to report auto destroy run results        Destroy at a specific day and time  To schedule an auto destroy run at a specific time in HCP Terraform  1  Navigate to the workspace s   Settings       Destruction and Deletion   page  1  Under   Automatically destroy    click   Set up auto destroy    1  Enter the desired date and time  HCP Terraform defaults to your local time zone for scheduling and displays how long until the scheduled operation  1  Click   Confirm auto destroy     To cancel a scheduled auto destroy run in HCP Terraform  1  Navigate to the workspace s   Settings       Destruction and Deletion   page  1  Under   Automatically destroy    click   Edit   next to your scheduled run s details  1  Click   Remove          Destroy if a workspace is inactive  You can configure HCP Terraform to automatically destroy a workspace s infrastructure after a period of inactivity  A workspace is  inactive  if the workspace s state has not changed within your designated time period        Caution    As opposed to configuring an auto destroy run for a specific date and time  this setting  persists  after queueing auto destroy runs   If you configure a workspace to auto destroy its infrastructure when inactive  any run that updates Terraform state further delays the scheduled auto destroy time by the length of your designated timeframe   To schedule an auto destroy run after a period of workspace inactivity  1  Navigate to the workspace s   Settings       Destruction and Deletion   page  1  Under   Automatically destroy    click   Set up auto destroy    1  Click the   Destroy if inactive   toggle  1  Select or customize a desired timeframe of inactivity  1  Click   Confirm auto destroy     When configured for the first time  the auto destroy duration setting displays the scheduled date and time that HCP Terraform will perform the auto destroy run  Subsequent auto destroy runs and Terraform runs that update state both update the next scheduled auto destroy date   After HCP Terraform completes a manual or automatic destroy run  it waits until further state updates to schedule a new auto destroy run   To remove your workspace s auto destroy based on inactivity  1  Navigate to the workspace s   Settings       Destruction and Deletion   page  1  Under   Auto destroy settings    click   Edit   to change the auto destroy settings  1  Click   Remove        Delete Workspace  Terraform does not automatically destroy managed infrastructure when you delete a workspace   After you delete the workspace and its state file  Terraform can  no longer track or manage  that infrastructure  You must manually delete or  import   terraform cli commands import  any remaining resources into another Terraform workspace   By default   workspace administrators   terraform cloud docs users teams organizations permissions workspace admins  can only delete unlocked workspaces that are not managing any infrastructure  Organization owners can force delete a workspace to override these protections  Organization owners can also configure the  organization s settings   terraform cloud docs users teams organizations organizations general  to let workspace administrators force delete their own workspaces      Data Retention Policies   EnterpriseAlert  Data retention policies are exclusive to Terraform Enterprise  and not available in HCP Terraform   a href  https   developer hashicorp com terraform enterprise  Learn more about Terraform Enterprise  a     EnterpriseAlert   Define configurable data retention policies for workspaces to help reduce object storage consumption  You can define a policy that allows Terraform to  soft delete  the backing data associated with configuration versions and state versions  Soft deleting refers to marking a data object for garbage collection so that Terraform can automatically delete the object after a set number of days   Once an object is soft deleted  any attempts to read the object will fail  Until the garbage collection grace period elapses  you can still restore an object using the APIs described in the  configuration version documentation   terraform enterprise api docs configuration versions  and  state version documentation   terraform enterprise api docs state versions   After the garbage collection grace period elapses  Terraform permanently deletes the archivist storage   The  organization policy   terraform enterprise users teams organizations organizations destruction and deletion  is the default policy applied to workspaces  but members of individual workspaces can override the policy for their workspaces   The workspace policy always overrides the organization policy  A workspace admin can set or override the following data retention policies       Organization default policy       Do not auto delete       Auto delete data    Setting the data retention policy to   Organization default policy   disables the other data retention policy settings


terraform page title Notifications Workspaces HCP Terraform HCP Terraform can use webhooks to notify external systems about run progress and other events Each workspace has its own notification settings and can notify up to 20 destinations Notifications Learn how to use webhooks to notify external systems about run progress and other events Create and enable workspace notifications

Answer:
---
page_title: Notifications - Workspaces - HCP Terraform
description: >-
  Learn how to use webhooks to notify external systems about run progress and other events. Create and enable workspace notifications.
---

# Notifications

HCP Terraform can use webhooks to notify external systems about run progress and other events. Each workspace has its own notification settings and can notify up to 20 destinations.

-> **Note:** [Speculative plans](/terraform/cloud-docs/run/modes-and-options#plan-only-speculative-plan) and workspaces configured with `Local` [execution mode](/terraform/cloud-docs/workspaces/settings#execution-mode) do not support notifications.

Configuring notifications requires admin access to the workspace. Refer to [Permissions](/terraform/cloud-docs/users-teams-organizations/permissions) for details.

[permissions-citation]: #intentionally-unused---keep-for-maintainers

-> **API:** Refer to [Notification Configuration APIs](/terraform/cloud-docs/api-docs/notification-configurations).

## Viewing and Managing Notification Settings

To add, edit, or delete notifications for a workspace, go to the workspace and click **Settings > Notifications**. The **Notifications** page appears, showing existing notification configurations.

## Creating a Notification Configuration

A notification configuration specifies a destination URL, a payload type, and the events that should generate a notification. To create a notification configuration:

1.  Click **Settings > Notifications**. The **Notifications** page appears.

2.  Click **Create a Notification**. The **Create a Notification** form appears.

3.  Configure the notifications:

- **Destination:** HCP Terraform can deliver either a generic payload or a payload formatted specifically for Slack, Microsoft Teams, or Email. Refer to [Notification Payloads](#notification-payloads) for details.
- **Name:** A display name for this notification configuration.
- **Webhook URL** This URL is only available for generic, Slack, and Microsoft Teams webhooks. The webhook URL is the destination for the webhook payload. This URL must accept HTTP or HTTPS `POST` requests and should be able to use the chosen payload type. For details, refer to Slack's documentation on [creating an incoming webhook](https://api.slack.com/messaging/webhooks#create_a_webhook) and Microsoft's documentation on [creating a workflow from a channel in teams](https://support.microsoft.com/en-us/office/creating-a-workflow-from-a-channel-in-teams-242eb8f2-f328-45be-b81f-9817b51a5f0e).
- **Token** (Optional) This notification is only available for generic webhooks. A token is an arbitrary secret string that HCP Terraform will use to sign its notification webhooks. Refer to [Notification Authenticity][inpage-hmac] for details. You cannot view the token after you save the notification configuration.
- **Email Recipients** This notification is only available for emails. Select users that should receive notifications.

- **Workspace Events**: HCP Terraform can send notifications for all events or only for specific events. The following events are available:

  - **Drift**: HCP Terraform detected configuration drift. This notification is only available if you enable [health assessments](/terraform/cloud-docs/workspaces/health) for the workspace.
  - **Check Failure:** HCP Terraform detected one or more failed continuous validation checks. This notification is only available if you enable health assessments for the workspace.
  - **Health Assessment Fail**: A health assessment failed. This notification is only available if you enable health assessments for the workspace. Health assessments fail when HCP Terraform cannot perform drift detection, continuous validation, or both. The notification does not specify the cause of the failure, but you can use the [Assessment Result](/terraform/cloud-docs/api-docs/assessment-results) logs to help diagnose the issue.
  - **Auto destroy reminder**: Sends reminders 12 and 24 hours before a scheduled auto destroy run.
  - **Auto destroy results**: HCP Terraform performed an auto destroy run in the workspace. Reports both successful and errored runs.

<!-- BEGIN: TFC:only name:pnp-callout -->
@include 'tfc-package-callouts/health-assessments.mdx'
<!-- END: TFC:only name:pnp-callout -->

- **Run Events:** HCP Terraform can send notifications for all events or only for specific events. The following events are available:
  - **Created**: A run begins and enters the [Pending stage](/terraform/enterprise/run/states#the-pending-stage).
  - **Planning**: A run acquires the lock and starts to execute.
  - **Needs Attention**: A plan has changes and Terraform requires user input to continue. This event may include approving the plan or a [policy override](/terraform/enterprise/run/states#the-policy-check-stage).
  - **Applying**: A run enters the [Apply stage](/terraform/enterprise/run/states#the-apply-stage), where Terraform makes the infrastructure changes described in the plan.
  - **Completed**: A run completed successfully.
  - **Errored**: A run terminated early due to error or cancellation.

4.  Click **Create a notification**.

## Enabling and Verifying a Configuration

To enable or disable a configuration, toggle the **Enabled/Disabled** switch on its detail page. HCP Terraform will attempt to verify the configuration for generic and slack webhooks by sending a test message, and will enable the notification configuration if the test succeeds.

For a verification to be successful, the destination must respond with a `2xx` HTTP code. If verification fails, HCP Terraform displays the error message and the configuration will remain disabled.

For both successful and unsuccessful verifications, click the **Last Response** box to view more information about the verification results. You can also send additional test messages with the **Send a Test** link.

## Notification Payloads

### Slack

Notifications to Slack will contain the following information:

- The run's workspace (as a link)
- The HCP Terraform username and avatar of the person that created the run
- The run ID (as a link)
- The reason the run was queued (usually a commit message or a custom message)
- The time the run was created
- The event that triggered the notification and the time that event occurred

### Microsoft Teams

Notifications to Microsoft Teams contain the following information:

- The run's workspace (as a link)
- The HCP Terraform username and avatar of the person that created the run
- The run ID
- A link to view the run
- The reason the run was queued (usually a commit message or a custom message)
- The time the run was created
- The event that triggered the notification and the time that event occurred

### Email

Email notifications will contain the following information:

- The run's workspace (as a link)
- The run ID (as a link)
- The event that triggered the notification, and if the run needs to be acted upon or not

### Generic

A generic notification will contain information about a run and its state at the time the triggering event occurred. The complete generic notification payload is described in the [API documentation][generic-payload].

[generic-payload]: /terraform/cloud-docs/api-docs/notification-configurations#notification-payload

Some of the values in the payload can be used to retrieve additional information through the API, such as:

- The [run ID](/terraform/cloud-docs/api-docs/run#get-run-details)
- The [workspace ID](/terraform/cloud-docs/api-docs/workspaces#list-workspaces)
- The [organization name](/terraform/cloud-docs/api-docs/organizations#show-an-organization)

## Notification Authenticity

[inpage-hmac]: #notification-authenticity

Slack notifications use Slack's own protocols for verifying HCP Terraform's webhook requests.

Generic notifications can include a signature for verifying the request. For notification configurations that include a secret token, HCP Terraform's webhook requests will include an `X-TFE-Notification-Signature` header, which contains an HMAC signature computed from the token using the SHA-512 digest algorithm. The receiving service is responsible for validating the signature. More information, as well as an example of how to validate the signature, can be found in the [API documentation](/terraform/cloud-docs/api-docs/notification-configurations#notification-authenticity).

page title  Notifications   Workspaces   HCP Terraform description       Learn how to use webhooks to notify external systems about run progress and other events  Create and enable workspace notifications         Notifications  HCP Terraform can use webhooks to notify external systems about run progress and other events  Each workspace has its own notification settings and can notify up to 20 destinations        Note     Speculative plans   terraform cloud docs run modes and options plan only speculative plan  and workspaces configured with  Local   execution mode   terraform cloud docs workspaces settings execution mode  do not support notifications   Configuring notifications requires admin access to the workspace  Refer to  Permissions   terraform cloud docs users teams organizations permissions  for details    permissions citation    intentionally unused   keep for maintainers       API    Refer to  Notification Configuration APIs   terraform cloud docs api docs notification configurations       Viewing and Managing Notification Settings  To add  edit  or delete notifications for a workspace  go to the workspace and click   Settings   Notifications    The   Notifications   page appears  showing existing notification configurations      Creating a Notification Configuration  A notification configuration specifies a destination URL  a payload type  and the events that should generate a notification  To create a notification configuration   1   Click   Settings   Notifications    The   Notifications   page appears   2   Click   Create a Notification    The   Create a Notification   form appears   3   Configure the notifications       Destination    HCP Terraform can deliver either a generic payload or a payload formatted specifically for Slack  Microsoft Teams  or Email  Refer to  Notification Payloads   notification payloads  for details      Name    A display name for this notification configuration      Webhook URL   This URL is only available for generic  Slack  and Microsoft Teams webhooks  The webhook URL is the destination for the webhook payload  This URL must accept HTTP or HTTPS  POST  requests and should be able to use the chosen payload type  For details  refer to Slack s documentation on  creating an incoming webhook  https   api slack com messaging webhooks create a webhook  and Microsoft s documentation on  creating a workflow from a channel in teams  https   support microsoft com en us office creating a workflow from a channel in teams 242eb8f2 f328 45be b81f 9817b51a5f0e       Token    Optional  This notification is only available for generic webhooks  A token is an arbitrary secret string that HCP Terraform will use to sign its notification webhooks  Refer to  Notification Authenticity  inpage hmac  for details  You cannot view the token after you save the notification configuration      Email Recipients   This notification is only available for emails  Select users that should receive notifications       Workspace Events    HCP Terraform can send notifications for all events or only for specific events  The following events are available         Drift    HCP Terraform detected configuration drift  This notification is only available if you enable  health assessments   terraform cloud docs workspaces health  for the workspace        Check Failure    HCP Terraform detected one or more failed continuous validation checks  This notification is only available if you enable health assessments for the workspace        Health Assessment Fail    A health assessment failed  This notification is only available if you enable health assessments for the workspace  Health assessments fail when HCP Terraform cannot perform drift detection  continuous validation  or both  The notification does not specify the cause of the failure  but you can use the  Assessment Result   terraform cloud docs api docs assessment results  logs to help diagnose the issue        Auto destroy reminder    Sends reminders 12 and 24 hours before a scheduled auto destroy run        Auto destroy results    HCP Terraform performed an auto destroy run in the workspace  Reports both successful and errored runs        BEGIN  TFC only name pnp callout      include  tfc package callouts health assessments mdx       END  TFC only name pnp callout          Run Events    HCP Terraform can send notifications for all events or only for specific events  The following events are available        Created    A run begins and enters the  Pending stage   terraform enterprise run states the pending stage         Planning    A run acquires the lock and starts to execute        Needs Attention    A plan has changes and Terraform requires user input to continue  This event may include approving the plan or a  policy override   terraform enterprise run states the policy check stage         Applying    A run enters the  Apply stage   terraform enterprise run states the apply stage   where Terraform makes the infrastructure changes described in the plan        Completed    A run completed successfully        Errored    A run terminated early due to error or cancellation   4   Click   Create a notification         Enabling and Verifying a Configuration  To enable or disable a configuration  toggle the   Enabled Disabled   switch on its detail page  HCP Terraform will attempt to verify the configuration for generic and slack webhooks by sending a test message  and will enable the notification configuration if the test succeeds   For a verification to be successful  the destination must respond with a  2xx  HTTP code  If verification fails  HCP Terraform displays the error message and the configuration will remain disabled   For both successful and unsuccessful verifications  click the   Last Response   box to view more information about the verification results  You can also send additional test messages with the   Send a Test   link      Notification Payloads      Slack  Notifications to Slack will contain the following information     The run s workspace  as a link    The HCP Terraform username and avatar of the person that created the run   The run ID  as a link    The reason the run was queued  usually a commit message or a custom message    The time the run was created   The event that triggered the notification and the time that event occurred      Microsoft Teams  Notifications to Microsoft Teams contain the following information     The run s workspace  as a link    The HCP Terraform username and avatar of the person that created the run   The run ID   A link to view the run   The reason the run was queued  usually a commit message or a custom message    The time the run was created   The event that triggered the notification and the time that event occurred      Email  Email notifications will contain the following information     The run s workspace  as a link    The run ID  as a link    The event that triggered the notification  and if the run needs to be acted upon or not      Generic  A generic notification will contain information about a run and its state at the time the triggering event occurred  The complete generic notification payload is described in the  API documentation  generic payload     generic payload    terraform cloud docs api docs notification configurations notification payload  Some of the values in the payload can be used to retrieve additional information through the API  such as     The  run ID   terraform cloud docs api docs run get run details    The  workspace ID   terraform cloud docs api docs workspaces list workspaces    The  organization name   terraform cloud docs api docs organizations show an organization      Notification Authenticity   inpage hmac    notification authenticity  Slack notifications use Slack s own protocols for verifying HCP Terraform s webhook requests   Generic notifications can include a signature for verifying the request  For notification configurations that include a secret token  HCP Terraform s webhook requests will include an  X TFE Notification Signature  header  which contains an HMAC signature computed from the token using the SHA 512 digest algorithm  The receiving service is responsible for validating the signature  More information  as well as an example of how to validate the signature  can be found in the  API documentation   terraform cloud docs api docs notification configurations notification authenticity