Configure teardown workflows

Teardown workflows clean up resources for templates, workflows, and preview environments. Use teardowns to destroy OpenTofu infrastructure, run cleanup jobs, call external APIs, or perform other cleanup tasks.

Teardowns are defined in the teardownSpec section of your template definition. The structure mirrors your template’s spec, but instead of provisioning resources, it destroys them using a separate set of nodes designed for cleanup operations.

Configure teardowns through the visual editor or by editing your template definition directly.

1. Navigate to your template, workflow, or preview blueprint

2. Click Settings

3. Scroll to Teardown

4. Click Add teardown specification

5. Add nodes to define your cleanup workflow (see available nodes below)

6. Configure each node with the required settings

7. Click Save

Teardown workflows support a limited set of nodes:

• Run job: Run a job to execute cleanup scripts
• Message: Send teardown notifications
• Run action: Execute actions like running commands on a pod or restoring backups
• OpenTofu destroy: Destroy infrastructure created by an OpenTofu node
• Await condition: Wait for external conditions
• Approval: Require manual approval before proceeding

The OpenTofu destroy node removes all infrastructure created by a corresponding OpenTofu node. To reference an OpenTofu node, set a ref on it in your template spec.

{
  "spec": {
    "kind": "Workflow",
    "spec": {
      "type": "sequential",
      "steps": [
        {
          "kind": "OpenTofu",
          "ref": "infrastructure",
          "spec": {
            "stateKey": "e4bd4d08-7165-41ae-b099-ad5d13c4d86e",
            "spec": {
              "resource": {
                "aws_s3_bucket": {
                  "bucket": "my-bucket-name"
                }
              }
            }
          }
        }
      ]
    }
  },
  "teardownSpec": {
    "spec": {
      "kind": "Workflow",
      "spec": {
        "type": "sequential",
        "steps": [
          {
            "kind": "OpenTofuDestroy",
            "spec": {
              "nodeRef": "infrastructure"
            }
          }
        ]
      }
    }
  }
}

The OpenTofu destroy node uses the nodeRef field to target the OpenTofu node you want to destroy.

Teardown runs inherit refs from the most recent successful setup run. This lets you reference resources created during setup using the same ${refs.nodeName.id} syntax.

For example, if your setup workflow creates a service, your teardown can reference its ID:

{
  "teardownSpec": {
    "spec": {
      "steps": [
        {
          "kind": "RunJob",
          "spec": {
            "command": "cleanup ${refs.api.id}"
          }
        }
      ]
    }
  }
}

The teardown will use the service ID from the most recent successful setup run.

Teardown behavior depends on whether you are using preview environments or templates and workflows.

Preview environments

Preview environments run teardowns automatically when you delete an environment. To skip the teardown, enable Skip teardown when manually deleting the environment through the UI.

Templates and workflows

Templates and workflows require manual teardown execution from the UI or API. Teardowns do not run automatically when you delete a template or workflow.

The failure policy controls what happens when a teardown run fails. Configure this in the teardownSpec.failurePolicy field:

{
  "teardownSpec": {
    "spec": {},
    "failurePolicy": "block"
  }
}

Available policies:

• ignore (default): Deletes resources regardless of teardown outcome
• block: Halts deletion and marks the environment as failed if teardown fails

Use block when teardown failures could leave orphaned resources on third-party providers that may incur additional costs. Use ignore when teardown is best effort and should not prevent deletion.