Namespaces are Kubernetes objects that partition a cluster into virtual clusters. Each Kubernetes object has a unique identity, defined by its name and the namespace it belongs to.
This article will show you how to delete a Kubernetes namespace. Alongside the standard namespace removal procedure, it will provide an additional method for troubleshooting problems concerning namespaces stuck in the terminating status.
- A Kubernetes cluster
- kubectl installed
Delete Kubernetes Namespace (Standard Method)
The standard method for deleting any Kubernetes namespace is using the dedicated kubectl command,
kubectl delete namespace [your-namespace]
The output of the command confirms the deletion of the namespace:
Force Delete a Kubernetes Namespace
Sometimes a user deletes a namespace before all its resources have been removed. This action may cause the namespace to become permanently stuck in the
Terminating status. Kubernetes does not allow creating another namespace with the same name until the deletion process is finished.
Note: Learn how can you create Kubernetes namespace after you finished the deletion process.
Check the status of the deleted namespace by using the
kubectl get command:
kubectl get namespace [your-namespace]
If the namespace was deleted successfully, Kubernetes returns an error:
However, if the deletion did not complete successfully, the status of the namespace is listed as
To force delete a Kubernetes namespace, remove the finalizer from the namespace's configuration. The finalizer is a Kubernetes resource whose purpose is to prohibit the force removal of an object.
The steps below demonstrate the procedure for removing the finalizer from the namespace configuration.
1. Display the namespace configuration in YAML format:
kubectl get namespace [your-namespace] -o yaml
2. Check if a finalizer exists in the
spec field. The example shows the
kubernetes finalizer in the configuration of
3. Copy the JSON-formatted output of the
kubectl get command to the tmp.json file. The file will be used to communicate the changes to the Kubernetes API.
kubectl get namespace [your-namespace] -o json >tmp.json
4. Edit the tmp.json file using a text editor:
Remove all the finalizers from the
spec.finalizers field. After editing, the file should resemble the example below:
Save and exit the file when you finish editing it.
5. Type the following command in the terminal to use HTTP proxy for accessing the Kubernetes API:
If successful, the proxy starts serving on an IP address specific to your cluster configuration.
6. Leave the proxy running in the terminal and open another terminal window.
7. Execute the following curl command to issue an API call to the Kubernetes API:
curl -k -H "Content-Type: application/json" -X PUT --data-binary @tmp.json http://127.0.0.1:8001/api/v1/namespaces/[your-namespace]/finalize
If successful, the command displays the namespace configuration information. The finalizers are not in the configuration anymore:
To confirm that you removed the namespace, list available namespaces with
kubectl get namespace
If the deletion is completed successfully, the namespace does not show in the list:
Note: BMC allows DevOps teams to utilize the Kubernetes API for BMC resource provisioning. The BMC controller for Kubernetes is available on phoenixNAP's official GitHub page.
After reading this article, you should know how to remove a Kubernetes namespace from your cluster. The article explained the standard
kubectl method for deleting a namespace and the force removal method that utilizes a Kubernetes API call.