Delete Kubernetes Namespaces With kubectl

The short answer

In Kubernetes, to delete a namespace, you can use the [.inline-code]kubectl delete[.inline-code] command as follows:

$ kubectl delete namespace <namespace>

Where:

• [.inline-code]namespace[.inline-code] is the name of the namespace you want to delete.

For example, the following command will delete the Kubernetes namespace named [.inline-code]dev[.inline-code]:

 $ kubectl delete namespace dev

To retrieve the list of available namespaces in your cluster, you can read our other article on how to list namespaces in Kubernetes.

Note that deleting a namespace is an irreversible action and should be performed with caution.

[#delete-multiple-namespaces] Deleting multiple namespaces [#delete-multiple-namespaces]

To delete multiple namespaces at once, you can use the [.inline-code]kubectl delete[.inline-code] command as follows:

 $ kubectl delete namespace <namespace …>

Where:

• [.inline-code]namespace …[.inline-code] is a list of namespaces separated by a space character.

For example, the following command will delete the [.inline-code]dev[.inline-code], [.inline-code]qa[.inline-code], and [.inline-code]staging[.inline-code] namespaces all at once:

 $ kubectl delete namespace dev qa staging

[#delete-all-namespaces] Deleting all namespaces [#delete-all-namespaces]

To delete all the namespaces in a cluster at once, you can use the [.inline-code]kubectl delete[.inline-code] command with the [.inline-code]--all[.inline-code] flag as follows:

 $ kubectl delete namespace --all

[#delete-namespace-by-label] Deleting namespaces by label [#delete-namespace-by-label]

In Kubernetes, labels are key-value pairs attached to the Kubernetes objects that organize resources based on specific criteria.

To delete one or more namespaces based on a label, you can use the [.inline-code]-l[.inline-code] flag (short for [.inline-code]--label[.inline-code]) as follows:

 $ kubectl delete namespace -l <label>=<value>

Where:

• [.inline-code]label[.inline-code] is the key of the label. 

• [.inline-code]value[.inline-code] is the value associated with the label.

For example, the following command will remove all the namespaces with the label [.inline-code]env=dev[.inline-code]:

 $ kubectl delete namespace -l env=dev

On the other hand, to delete all the namespaces except the ones with a specific label, you can place an exclamation mark [.inline-code]![.inline-code] before the label key as follows:

$ kubectl delete namespace -l !<label>=<value>

For example, the following command will delete all the namespaces in the current cluster except the namespace with the label [.inline-code]app=production[.inline-code]:

 $ kubectl delete namespace -l "!app=production"

[#simulate-namespace-deletion] Simulating a namespace deletion [#simulate-namespace-deletion]

In Kubernetes, you can simulate the deletion of a namespace using the the [.inline-code]--dry-run[.inline-code] flag as follows:

 $ kubectl delete namespace <namespace> --dry-run=<strategy>

Where:

• [.inline-code]strategy[.inline-code] can be one of [.inline-code]none[.inline-code], [.inline-code]client[.inline-code], or [.inline-code]server[.inline-code].

For example, the following command will simulate the deletion of the [.inline-code]dev[.inline-code] namespace on the client side:

 $ kubectl delete namespace dev --dry-run=client

[#client-vs-server-simulation] Client-side vs. server-side simulation [#client-vs-server-simulation]

When using the [.inline-code]--dry-run=client[.inline-code] flag, Kubernetes simulates the deletion operation on the client side, which means that [.inline-code]kubectl[.inline-code] locally validates the request but doesn't communicate with the server.

This is useful for quickly checking the syntax and feasibility of the deletion operation without impacting the cluster.

On the other hand, when using the [.inline-code]--dry-run=server[.inline-code] flag, Kubernetes simulates the deletion operation on the server side, which means that [.inline-code]kubectl[.inline-code] sends the deletion request to the Kubernetes API server, but the server does not actually execute the deletion.

Instead, it validates the request and returns the intended changes as if they were executed, allowing you to preview the server's response without affecting the cluster's actual state.

[#delete-namespaces-with-a-grace-period] Specifying a grace period [#delete-namespaces-with-a-grace-period]

In Kubernetes, the grace period refers to the amount of time given to a resource to perform any necessary cleanup or shutdown tasks before it is forcefully terminated.

To delete a namespace and all its related resources with a grace period expressed in seconds, you can use the [.inline-code]--grace-period[.inline-code] flag as follows:

 $ kubectl delete namespace <namespace> --grace-period=<seconds>

Note that the grace period will default to 30 seconds if the [.inline-code]--grace-period[.inline-code] flag is omitted.

For example, the following command will remove the [.inline-code]dev[.inline-code] namespace and wait 90 seconds before forcefully terminating any related resources:

 $ kubectl delete namespace dev --grace-period=90

[#delete-namespaces-forcefully] Forcefully deleting a namespace [#delete-namespaces-forcefully]

To delete a namespace and its associated resources immediately without waiting for them to gracefully shutdown, you can use the [.inline-code]--force[.inline-code] flag as follows:

 $ kubectl delete namespace <namespace> --force

Note that the [.inline-code]--force[.inline-code] flag is mandatory when setting the grace period to [.inline-code]0[.inline-code]:

 $ kubectl delete namespace <namespace> --grace-period=0 --force

[#easily-recall-syntax-with-ai] Easily retrieve this command using Warp’s AI Command Search [#easily-recall-syntax-with-ai]

If you’re using Warp as your terminal, you can easily retrieve this command using the Warp AI Command Search feature:

Entering [.inline-code]kubernetes delete namespace with delay[.inline-code] in the AI Command Suggestions will prompt a list of [.inline-code]kubectl[.inline-code] commands that can then quickly be inserted into your shell by doing [.inline-code]CMD+ENTER[.inline-code].

[#remove-namespace-finalizers] Removing the finalizers attached to a namespace [#remove-namespace-finalizers]

When trying to delete a namespace, it may happen that some of its related resources get stuck in a "Terminating" state, thus preventing its deletion.

To effectively remove any finalizers attached to the specified namespace, allowing it to be deleted without any final cleanup or processing actions taking place, you can use the [.inline-code]kubectl patch[.inline-code] command as follows:

 $ kubectl patch namespace <namespace> -p '{"metadata":{"finalizers":[]}}' --type=merge

Note that this command should be used with caution, as finalizers are important for the orderly deletion of resources.

[#common-errors] Common errors [#common-errors]

Here are some of the most common errors when deleting a namespace in Kubernetes.

[#permission-denied] Permission denied [#permission-denied]

The [.inline-code]kubectl[.inline-code] command will output an error when trying to delete a namespace with a Kubernetes user lacking the necessary roles and permissions.

For example, trying to remove the default namespace will result in the following error:

 Error from server (Forbidden): namespaces "default" is forbidden: this namespace may not be deleted

[#namespace-not-found] Namespace not found [#namespace-not-found]

The [.inline-code]kubectl[.inline-code] command will output an error if the specified namespace doesn't exist.

For example, trying to remove the non-existent [.inline-code]test[.inline-code] namespace will result in the following error:

 Error from server (NotFound): namespaces "test" not found