A Kubernetes namespace cannot be deleted because a finalizer is blocking termination. Finalizers ensure cleanup operations complete before a resource is removed.
Fixes finalizers stuck on namespace
kubectl get namespace my-namespace -o yamlkubectl get namespace my-namespace -o yamlfinalizers stuck on namespace
On this page
Finalizers are Kubernetes hooks that prevent resource deletion until certain cleanup operations finish. When a namespace has finalizers that don't complete (often due to missing controllers or unresponsive webhooks), the namespace enters a "Terminating" state indefinitely. This commonly happens when a custom resource or operator is removed without cleaning up its finalizers.
Get details on the terminating namespace:
kubectl get namespace my-namespace -o yamlLook for the finalizers list under metadata. Common ones include:
- kubernetes
- foregroundDeletion
- Custom finalizers like myoperator.io/cleanup
If the finalizer comes from an operator, verify it's deployed:
kubectl get deployment -A | grep -i operator-nameIf the operator is missing or stuck, that's the problem.
Extract the namespace YAML without finalizers:
kubectl get namespace my-namespace -o json | jq 'del(.metadata.finalizers)' | kubectl replace --raw /api/v1/namespaces/my-namespace -f -Or edit directly:
kubectl edit namespace my-namespace
# Remove the finalizers array entirelyAfter removing finalizers, the namespace should delete immediately:
kubectl get namespace my-namespace
# Should show: No resources foundFor operators you deploy, ensure they have proper cleanup:
# Before removing an operator, clean up its finalizers
kubectl delete crds $(kubectl get crds --all-namespaces -o name | grep myoperator.io)
# Or restart the operator to let it clean up gracefully
kubectl rollout restart deployment/my-operator -n operatorsUse kubectl patch to remove finalizers on live resources: kubectl patch namespace my-namespace -p '{"metadata":{"finalizers":null}}'. Finalizerscannot be completely avoided, but operators should implement proper cleanup logic. Use admission webhooks carefully—a failing webhook can block namespace deletion. In production, monitor finalizer operations and set timeouts on long-running cleanup tasks.