How to Delete a Kubernetes Namespace

Introduction

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.

Prerequisites

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

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.

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

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:

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:

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.

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:

kubectl get namespace

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

Conclusion

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.