Destroy Workspaces

Learn how to destroy workspaces using an interactive guide, step-by-step instructions, and YAML.

You can perform specific operations against your workspace configuration. Similarly to provisioning a workspace, you can tear down the infrastructure state from a workspace without deleting the workspace itself. This guide walks you through how to create a Destroy pipeline to run the init, plan and destroy commands with OpenTofu or Terraform.

Interactive Guide

Step-by-Step

Follow these instructions to provision a workspace within the Harness Visual Editor.

1. In the Harness project pane, select Pipelines.

2. Click + Create a Pipeline to set up a new pipeline.

3. Click Add Stage and select Infrastructure from the Select Stage Type pane.

4. Enter a stage name, optional description, and tag, then select Set Up Stage.

5. On the Workspace tab, select an existing workspace or click + Create New Workspace to create one.

6. Go to the Execution tab. Under Common Operations, select Destroy to configure the workspace destruction process.

7. Select Use Strategy to automatically add init, plan, and destroy steps, or customize the pipeline by adding steps manually.

8. Click Save and then Run Pipeline to execute.

The plan-destroy step generates a Terraform plan. This Terraform plan is accessible to all the steps after the IaCM Terraform plan, and can be referenced using the expression <+pipeline.stages.STAGE_ID.spec.execution.steps.STEP_ID.output.outputVariables.parsedPlan>.

YAML

To destroy a workspace via YAML, use the template below. Replace bracketed placeholders as needed.

pipeline:
  name: <<PIPELINE NAME>>
  identifier: <<PIPELINE IDENTIFIER>>
  projectIdentifier: <<PROJECT IDENTIFIER>>
  orgIdentifier: <<ORG IDENTIFIER>>
  tags: {}
  stages:
    - stage:
        name: Destroy Stage
        identifier: destroy_stage
        type: IACM
        spec:
          workspace: <<WORKSPACE ID>>
          platform:
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud
            spec: {}
          execution:
            steps:
              - step:
                  type: IACMTerraformPlugin
                  name: init
                  identifier: init
                  spec:
                    command: init
                  timeout: 5m
              - step:
                  type: IACMTerraformPlugin
                  name: plan
                  identifier: plandestroy
                  spec:
                    command: plan-destroy
                  description: plan destroy
              - step:
                  type: IACMTerraformPlugin
                  name: destroy
                  identifier: destroy
                  spec:
                    command: destroy
                  description: destroy
                  timeout: 5m
        tags: {}

Notice the three steps to execute your init, plan and destroy commands.

---

REVIEW RESOURCES

After the plan is created, view resources and Terraform outputs on the Resources tab. Check which resources will be added, modified, or removed.

Troubleshooting

Plan-destroy fails with 404 Not Found — a resource in Terraform state was deleted outside of Terraform (for example, manually removed from the Harness platform or deleted by another pipeline). Terraform refreshes state before planning; when it queries the Harness API for a resource that no longer exists, the provider returns a 404 and the plan fails.

Add a removed block with lifecycle { destroy = false } to drop the resource from state without an API delete, then re-run plan-destroy. Alternatively, run terraform state rm if you have CLI access, or remove the orphaned entry via the Harness IaCM State tab.