Ephemeral refers to something that does not last for a long time. In HCP Terraform, a workspace is a group of infrastructure resources managed by Terraform. Hence, an ephemeral workspace does not last for a long time. This implies that it is suitable for IaC use cases where the resources are provisioned for a short duration, primarily for a proof of concept or to verify a specific functionality.
In this note, you will learn how to implement ephemeral workspace in your HCP Terraform organization.

Please note: Ephemeral workspace management with the Terraform provider is currently supported only for HCP Terraform Plus and Terraform Enterprise (GA) organizations. Please navigate to the Organization Settings → Plan & Billings to verify the current plan.

Pre-requisite:
Before we get started, please learn about HCP Terraform and how it differs from the community edition Terraform. It’ll also be helpful to study this note  - provisioning AWS resources with HCP Terraform. In that note, you’ll learn how to create an HCP Terraform organization, a project inside the organization, a workspace in a project, and store IAM credentials as secure variables in the workspace. You will also require a VCS (version control system) to associate with the workspace. For this use case, you may fork my GitHub repository: kunduso/hashitalk-2025-ephemeral-workpsace and refer to that in the HCP Terraform workspace. Please update the values of organization and workspaces properties in the provider.tf file with your organization and workspace values.

Setup:
Once you have all the required pre-requisites in place, you are ready to enable ephemeral workspace. On your workspace settings, scroll down and select the “Destruction and Deletion” option.

The above image is the settings of my HCP Terraform organization (kunduso) with a workspace (app-three).
Under the “Destruction and Deletion” settings, examine “Automatically destroy” and click on the button - “Set up auto-destroy”.

Two mechanisms support ephemeral workspace. If you want the workspace to be decommissioned on a particular date, select - “Destroy at specific time”. Alternatively, suppose you are unsure how long it would take to test out a particular POC or use case and would want the workspace active until there is no activity for a specific time. In that case, you may select “Destroy if inactive” and specify how long the activity will be watched before decommissioning the workspace.

Since I was testing out the functionality, I selected “Destroy if inactive” and set the timer to 1 hour (the shortest possible time frame).

I made my code changes in a non-main branch, pushed the changes up, and created a pull request that generated a speculative plan. After merging the changes to the main branch, an HCP Terraform workflow kicked off and created the AWS cloud resources.

After the pipeline had succeeded, the workspace was updated with information about the AWS cloud resources, and the timer to decommission the workflow also started.

After an hour of no activity, a new run was auto-triggered via an API to start the decommissioning process.

What is considered an activity?
A terraform apply step is considered an activity, so if you’ve implemented a speculative plan (as part of a pull request), that will not be viewed as an activity.

Please note that you may also decommission a workspace from the Project settings. Navigate to Project → select the Project (name) → Settings → Auto-destroy workspaces, and click on the button “Set up default”.

And that brings us to the end of this note. We learned how to enable ephemeral workspaces with HCP Terraform. If you have any questions, please use the comments section to ask your question.