> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Finalizers Created by the ngrok Kubernetes Operator

> Learn about how the ngrok Kubernetes Operator uses finalizers to ensure proper cleanup of ngrok resources before deletion.

## What are finalizers?

Finalizers are **mechanisms in Kubernetes** that prevent a resource from being deleted until **certain cleanup operations** have been completed.
They act as a safeguard to ensure that dependent external resources, such as resources in your ngrok account that the Operator creates/updates/deletes, are properly removed before the Kubernetes object disappears.

When a resource with a finalizer is deleted, Kubernetes **does not immediately remove it**.
Instead, the resource enters a **"deletion in progress"** state, allowing the Operator to perform necessary cleanup tasks before the resource is fully deleted.
If you are using the ngrok Kubernetes Operator, and delete resources such as `CloudEndpoint`/`AgentEndpoint` and notice that they are not going away, this is likely the case.

***

## How the Operator uses finalizers

The ngrok Kubernetes Operator **automatically attaches finalizers** to its **custom resources** to make sure that any associated resources in your ngrok account are properly cleaned up before deletion.

### Why does the Operator use finalizers?

* **Prevents orphaned resources**
  * Ensures ngrok resources (for example, tunnels, endpoints) are deleted before removing the Kubernetes object.
* **Ensures a clean teardown**
  * Avoids leaving behind unnecessary external configurations.
* **Prevents inconsistencies**
  * Ensures that removing a Kubernetes resource does not leave ghost services in your ngrok account.

***

## How finalizers work

1. **Resource is Marked for Deletion**\
   When a user deletes an ngrok **custom resource**, Kubernetes does **not** immediately remove it.
   Instead, it **sets a deletion timestamp** on the resource.

2. **The Operator detects the deletion request**\
   The ngrok Operator sees that the resource has a **finalizer** and begins the **cleanup process**.

3. **Cleanup operations are performed**

   * **Contacts the ngrok API** to delete the associated **tunnel, endpoint, or cloud resource**.
   * **Verifies successful cleanup** before proceeding.

4. **Finalizer is removed**\
   Once the ngrok resource is fully cleaned up, the Operator **removes the finalizer** from the Kubernetes object.

5. **Kubernetes deletes the resource**\
   With the finalizer removed, Kubernetes **completes the deletion process**, and the resource is fully removed from the cluster.

***

## Checking finalizers on a resource

To check if a resource has a finalizer, use:

```bash theme={null}
kubectl get <resource> <name> -o yaml
```

Example output:

```yaml theme={null}
apiVersion: ngrok.k8s.ngrok.com/v1
kind: CloudEndpoint
metadata:
  name: my-endpoint
  finalizers:
  - ngrok.k8s.ngrok.com/finalizer
```

## Manually removing finalizers

If the Operator is not responding or failing to clean up resources properly, you may need to manually remove the finalizer on a resource.
This may happen if you are uninstalling the Operator with `helm uninstall` and the Operator pods are removed before they have a chance to clean up the finalizers on all the resources that were
marked for deletion. When uninstalling the Operator, the [pre-delete cleanup hook](/k8s/installation/uninstall#how-the-uninstall-process-works) handles this automatically, but if it was disabled or failed, you may need to intervene manually.

<Warning title="Warning">
  This will bypass cleanup operations, potentially leaving behind orphaned resources in your ngrok account.
  Check your ngrok dashboard after performing this to ensure that the resource is removed from your account so that you are not billed for it.
</Warning>

```bash theme={null}
kubectl patch <resource> <name> --type=json -p '[{"op": "remove", "path": "/metadata/finalizers"}]'
```

## Removing finalizers from all ngrok resources

If you need to bulk-remove finalizers from all ngrok custom resources (for example, after an uninstall where the cleanup job did not complete), you can use the following script:

```bash theme={null}
for crd in $(kubectl get crds -o json | jq -r '.items[].metadata.name | select(contains("ngrok.com"))'); do
  kubectl get "$crd" --all-namespaces -o json | jq -r '.items[] | select(.metadata.finalizers) | "\(.metadata.namespace) \(.metadata.name)"' | \
  while read ns name; do
    kubectl patch "$crd" "$name" -n "$ns" --type=json \
      -p '[{"op": "remove", "path": "/metadata/finalizers"}]'
  done
done
```

This iterates through every ngrok CRD type, finds all instances across all namespaces, and removes their finalizers. After running this, any resources stuck in `Terminating` state should complete their deletion.

***

## See also

* To learn more about how the automated cleanup process handles finalizers during uninstall, see [Uninstalling the Operator](/k8s/installation/uninstall).
* See [Troubleshooting](/k8s/guides/troubleshooting#resources-not-getting-deleted) for help with resources that won't delete.