deletion.mdx

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

Destruction and Deletion

HCP Terraform workspaces have two primary delete actions:

• Destroying infrastructure deletes resources managed by the HCP Terraform workspace by triggering a destroy run.
• Deleting a workspace 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 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.

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.

You can also schedule 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.
2. Under Automatically destroy, click Set up auto-destroy.
3. Enter the desired date and time. HCP Terraform defaults to your local time zone for scheduling and displays how long until the scheduled operation.
4. 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.
2. Under Automatically destroy, click Edit next to your scheduled run's details.
3. 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.
2. Under Automatically destroy, click Set up auto-destroy.
3. Click the Destroy if inactive toggle.
4. Select or customize a desired timeframe of inactivity.
5. 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.
2. Under Auto-destroy settings, click Edit to change the auto-destroy settings.
3. 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 any remaining resources into another Terraform workspace.

By default, workspace administrators 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 to let workspace administrators force delete their own workspaces.

Data Retention Policies

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

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 and state version documentation. After the garbage collection grace period elapses, Terraform permanently deletes the archivist storage.

The organization policy 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.