To delete a Kubernetes namespace, you run kubectl delete namespace <name>, which removes the namespace and everything inside it. This command first marks the namespace for termination, then the Kubernetes control plane deletes all resources within it before removing the namespace itself. The rest of this article explains how the deletion works, what to do when it gets stuck, and how to avoid common pitfalls.
What Happens When You Delete a Namespace
When you issue kubectl delete namespace my-namespace, the API server records a deletion timestamp on the namespace object. This sets the namespace’s status to Terminating. The Kubernetes controller manager then runs a namespace lifecycle controller that:
- Deletes all API resources in the namespace (pods, services, configmaps, secrets, etc.).
- Waits for finalizers on those resources to complete.
- Removes the namespace object itself once all resources are gone.
Deletion is asynchronous. The command returns immediately after the namespace is marked for deletion, not after it’s actually gone. You can check progress with kubectl get namespaces — the namespace will show status Terminating until it disappears.
Why a Namespace Gets Stuck in Terminating
A namespace can remain in Terminating state for several reasons. The most common cause is a resource with a finalizer that never completes. Finalizers are keys on a resource that block deletion until the key is removed. For example, a custom resource definition (CRD) might have a finalizer that waits for an external controller to clean up something, but if that controller is not running, the finalizer never goes away.
Other causes include:
- API server is unreachable or a CRD is unavailable, so the controller cannot list resources to delete them.
- There are resources in the namespace that are not tracked by the namespace controller (e.g., resources from aggregated APIs).
- The namespace itself has a finalizer (rare, but possible with custom controllers).
When a namespace is stuck, kubectl get namespace <name> -o yaml will show a status.phase: Terminating and possibly a spec.finalizers list. The presence of kubernetes in that list is normal and not the problem; it’s the other finalizers that cause issues.
How to Force Delete a Stuck Namespace
If you’ve waited and the namespace is still Terminating, you have a few options. First, try to identify and remove the blocking finalizers. You can edit the namespace object to remove the finalizers:
- Run
kubectl get namespace <name> -o json > ns.json. - Open the file and remove the entries under
spec.finalizers(keep thekubernetesone if present, but removing it also works). - Run
kubectl replace --raw "/api/v1/namespaces/<name>/finalize" -f ns.json.
This tells the API server to finalize the namespace immediately, bypassing the finalizer logic. It’s a manual override and should be used with caution because it can leave orphaned resources.
Another approach is to delete the namespace with the --force --grace-period=0 flags. This is primarily for pods, but for namespaces it can sometimes work:
kubectl delete namespace <name> --force --grace-period=0If that doesn’t work, you can try deleting the namespace object directly from etcd (not recommended for production) or using a tool like kubectl proxy and sending a DELETE request with a special finalizer. The most reliable method is the finalizer removal via the finalize endpoint, as shown above.
Common Mistakes When Deleting a Namespace
The biggest mistake is deleting a namespace without checking what’s inside it. Deleting a namespace is irreversible — all pods, services, configmaps, secrets, and persistent volume claims (PVCs) are gone. There is no undo. Always verify with kubectl get all -n <name> and kubectl get pvc -n <name> before deleting.
Another mistake is assuming the namespace is deleted when the command returns. The command returns immediately, but the actual deletion may take seconds or minutes. If you immediately try to recreate the namespace, you might get a conflict because the old one is still terminating. Wait until kubectl get namespaces no longer shows it.
Also, be aware that deleting a namespace does not delete persistent volumes (PVs) that are not in the namespace. PVs are cluster-scoped, so they remain. If you want to delete the underlying storage, you must do that separately.
Alternatives to Deleting a Whole Namespace
If you only need to clean up some resources, consider deleting individual resources instead of the entire namespace. For example, to delete all pods in a namespace:
kubectl delete pods --all -n <name>To delete all resources of a certain type (e.g., deployments, services):
kubectl delete deployments --all -n <name>
kubectl delete services --all -n <name>If you want to remove everything but keep the namespace, you can use kubectl delete all --all -n <name> — but note that this does not delete PVCs or custom resources. For a more thorough cleanup, consider using a tool like kubectl delete $(kubectl get all -n <name> -o name) or a script that lists all resource types.
If you need to destroy an entire cluster, deleting the namespace is not the right tool — you’d use kubectl delete cluster or the cloud provider’s console.
How to Prevent Stuck Namespaces
To avoid getting stuck in the first place, follow these practices:
- Ensure all custom controllers that add finalizers are running and can complete their cleanup.
- When deleting a custom resource, remove its finalizers first if you know the controller is gone.
- Use
kubectl delete namespacewith a timeout (e.g.,--timeout=60s) to get feedback if it takes too long. - Monitor your namespace deletions in CI/CD pipelines — don’t assume they succeed instantly.
If you regularly delete namespaces as part of testing, consider using a tool like kubens or a script that waits for the namespace to be fully gone before proceeding.
Frequently Asked Questions
What does ‘kubectl delete namespace’ do to pods?
It deletes all pods in the namespace. Kubernetes sends a SIGTERM to each pod, waits for the grace period (default 30 seconds), then sends SIGKILL. If the pod is managed by a controller (like a Deployment), the controller will try to recreate it elsewhere — but since the namespace is being deleted, the controller itself is also deleted, so no new pods are created.
Can I delete a namespace that has a PVC?
Yes, the namespace deletion will attempt to delete the PVCs in it. However, the underlying PVs are cluster-scoped and will not be deleted automatically. You must delete the PVs manually if you want to free the storage.
Why is my namespace stuck in ‘Terminating’ for hours?
This usually means a finalizer is blocking deletion. Check the namespace YAML for finalizers and look for resources with finalizers that might be stuck. Remove the finalizers manually as described above, or investigate the controller that should be removing them.
Is it safe to force delete a namespace?
Force deleting a namespace by removing finalizers can leave behind orphaned resources, such as LoadBalancer services or custom resources, that are no longer tracked. It can also cause the API server to become inconsistent. Use it only as a last resort, and be prepared to clean up leftovers manually.
How do I delete a namespace without waiting?
You can set a short grace period with --grace-period=0 --force, but this still goes through the API server and may not bypass finalizers. The only way to truly skip finalizers is to edit the namespace’s finalizers list, as shown earlier.