How to Force‑Delete a Stuck Kubernetes Namespace (Step‑by‑Step Guide)

Problem Description

During testing a pod could not start because its namespace stayed in Terminating status.

kubectl get ns
NAME                   STATUS        AGE
configmap              Terminating   135d
default                Active        207d
harbor                 Active        207d
kube-flannel           Terminating   17m
kube-node-lease        Active        207d
kube-public            Active        207d
kube-system            Active        207d
kubekey-system         Active        207d
kubernetes-dashboard   Active        207d
local-path-storage     Active        187d
nginx                  Active        146d
test                   Terminating   126d

Even using kubectl delete ns test --force leaves the namespace stuck.

Inspecting Resources in the Namespace

No resources are found in the test namespace:

# kubectl get all -n test
No resources found in test namespace.

Additional checks with

kubectl api-resources -o name --verbs=list --namespaced | xargs -n 1 kubectl get --show-kind --ignore-not-found -n test

also return nothing.

Resolution Steps

1. Export the namespace definition to JSON: # kubectl get ns test -o json > test.json 2. Edit test.json and ensure the spec section is empty, removing the finalizers array:

{
  "spec": {}
}

3. Use the Kubernetes API to finalize the namespace (the API server requires a proxy on port 8081):

# kubectl proxy --port=8081
Starting to serve on 127.0.0.1:8081

4. Send a PUT request with the cleaned JSON:

curl -k \
  -H "Content-Type: application/json" \
  -X PUT \
  --data-binary @test.json \
  http://127.0.0.1:8081/api/v1/namespaces/test/finalize

The response confirms the namespace is finalized and still in Terminating phase, but with no remaining finalizers.

Verify Deletion

# kubectl get ns
NAME                   STATUS        AGE
configmap              Terminating   135d
default                Active        207d
harbor                 Active        207d
kube-flannel           Terminating   21m
kube-node-lease        Active        207d
kube-public            Active        207d
kube-system            Active        207d
kubekey-system         Active        207d
kubernetes-dashboard   Active        207d
local-path-storage     Active        187d
nginx                  Active        146d

The test namespace has been removed. The same method works for other namespaces stuck in Terminating . Note: avoid naming a namespace the same as a resource type (e.g., configmap) because it can cause the API to misinterpret the name.

For more details see the original article:

(© Original author, removed upon request)