# Deletion and Teardown

Deleting a `TerraformCluster`, `TerraformMachine` or `TerraformMachinePool` means running Terraform’s `destroy` in a Job, then removing what CAPTF stored about the object. Most of the time nothing needs doing: you delete the Cluster Cluster API owns and everything follows. This chapter explains the order things happen in, what holds a deletion, how a deletion ends, and what is left behind when you short-circuit it. The step-by-step recoveries stay in the [runbooks](<https://captf.io/docs/operator-guide/runbooks/index.md>); this chapter is the model behind them.

The pages:

1. This page: the rules in one table, and the pages that follow.
2. [Order and finalizers](<https://captf.io/docs/concepts/deletion/order/index.md>): who deletes what first, and when the finalizer comes off.
3. [The destroy Job](<https://captf.io/docs/concepts/deletion/destroy-job/index.md>): what runs, what does not gate it, and how it fails.
4. [Held deletions](<https://captf.io/docs/concepts/deletion/held/index.md>): missing or unreadable state, restore, and the abandon annotation.
5. [Terminating namespaces](<https://captf.io/docs/concepts/deletion/namespaces/index.md>): deletions that need no Job, and the Secrets that go with the namespace.
6. [Cleanup and garbage collection](<https://captf.io/docs/concepts/deletion/cleanup/index.md>): what the controller deletes, what Kubernetes deletes, and the RBAC sweep.
7. [`clusterctl move`](<https://captf.io/docs/concepts/deletion/move/index.md>): the delete that skips the delete path.
8. [Stripping a finalizer by hand](<https://captf.io/docs/concepts/deletion/manual-finalizer/index.md>): the consequences.
9. [My object will not delete](<https://captf.io/docs/concepts/deletion/troubleshooting/index.md>): a flowchart from the symptom to the action.

## In this section

- **Order and Finalizers**

  ---

  Who deletes what first, and when the finalizer comes off.
- **The Destroy Job**

  ---

  What runs, what does not gate it, and how it fails.
- **Terminating Namespaces**

  ---

  Deletions that need no Job, and the Secrets that go with the namespace.
- **Cleanup and Garbage Collection**

  ---

  What the controller deletes, what Kubernetes deletes, and the RBAC sweep.
- **My Object Will Not Delete**

  ---

  A flowchart from the symptom to the action.

## The rules

A deleting object follows these rules, in this order. The first that applies decides the pass.

| Situation | What happens | Page |
| --- | --- | --- |
| The object or its Cluster is paused | Nothing: a paused object runs only Job bookkeeping, so it neither destroys nor releases | [Order](<https://captf.io/docs/concepts/deletion/order/#pause-stops-a-deletion>) |
| A Job of the object is running | The deletion waits for it; the destroy starts after | [Order](<https://captf.io/docs/concepts/deletion/order/#the-finalizer>) |
| A `TerraformCluster` with machines or pools left | `DeletionBlocked=True`/`DependentsExist`, no destroy yet | [Order](<https://captf.io/docs/concepts/deletion/order/#the-cluster-waits-for-its-machines>) |
| No state, and the object never applied | The finalizer comes off at once | [Held](<https://captf.io/docs/concepts/deletion/held/#ever-applied>) |
| No state, and the object applied before | Held: `StateReadable=False`/`StateLost` | [Held](<https://captf.io/docs/concepts/deletion/held/index.md>) |
| State exists but cannot be read | Held: `StateCorrupt`, `StateEncrypted` or `StateInconsistent` | [Held](<https://captf.io/docs/concepts/deletion/held/index.md>) |
| Readable state | A destroy Job runs; no gate or approval applies | [Destroy](<https://captf.io/docs/concepts/deletion/destroy-job/index.md>) |
| The destroy succeeded | Cleanup runs and the finalizer comes off | [Cleanup](<https://captf.io/docs/concepts/deletion/cleanup/index.md>) |
| The destroy failed or cannot start | Retried with backoff, forever; the abandon annotation releases it | [Held](<https://captf.io/docs/concepts/deletion/held/#abandon>) |

## What the controller never does

- It never drops the finalizer while a state Secret may still describe live resources, except on an explicit abandon.
- It never destroys against a state it cannot read.
- It never invents inputs to destroy with: the destroy renders from the durable inputs Secret (or, for a cluster or pool without one, the current inputs when they build).
- It never skips the destroy because it failed. There is no skip-destroy annotation, only the [abandon](<https://captf.io/docs/concepts/deletion/held/#abandon>) one.

> [!NOTE]
>
> **See also**
>
> - [The Reconcile Lifecycle](<https://captf.io/docs/concepts/lifecycle/#deletion-order>) for the pass that runs all of this.
> - [Terraform State](<https://captf.io/docs/concepts/state/#state-on-deletion>) and [Lifecycle walkthroughs](<https://captf.io/docs/concepts/secret-management/lifecycle/#delete>) for the Secrets.
> - [Other manual actions](<https://captf.io/docs/concepts/approvals/other-manual-actions/#abandon-an-object>) for the abandon annotation next to the other manual fixes.
> - [Stuck Destroy](<https://captf.io/docs/operator-guide/runbooks/stuck-destroy/index.md>), [Unreadable State](<https://captf.io/docs/operator-guide/runbooks/state-unreadable/#deleting-while-state-is-unreadable>), [State Restore](<https://captf.io/docs/operator-guide/runbooks/state-restore/index.md>) and [clusterctl move](<https://captf.io/docs/operator-guide/runbooks/move/index.md>) for the commands.