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.

How to delete a Kubernetes namespace.


  • 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:

kubectl delete namespace [your-namespace]

The output of the command confirms the deletion of the namespace:

Deleting a namespace using kubectl delete namespace command.

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:

The output of the kubectl get namespace command if the namespace does not exist.

However, if the deletion did not complete successfully, the status of the namespace is listed as Terminating:

Using the kubectl get namespace command to check the status of a namespace.

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 test-namespace:

Displaying the configuration of a namespace in the yaml format.

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:

nano tmp.json

Remove all the finalizers from the spec.finalizers field. After editing, the file should resemble the example below:

Editing the tmp.json file to remove the finalizer.

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:

kubectl proxy

If successful, the proxy starts serving on an IP address specific to your cluster configuration.

Using the kubectl proxy command to access Kubernetes API.

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[your-namespace]/finalize

If successful, the command displays the namespace configuration information. The finalizers are not in the configuration anymore:

The output of the curl command showing the finalizer was successfully removed.

To confirm that you removed the namespace, list available namespaces with kubectl get:

kubectl get namespace

If the deletion is completed successfully, the namespace does not show in the list:

Checking if the namespace was successfully deleted.

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.