Delete Kubernetes Namespaces With kubectl

The short answer

In Kubernetes, to delete a namespace, you can use the kubectl delete command as follows:

$ kubectl delete namespace <namespace>

Where:

• namespace is the name of the namespace you want to delete.

For example, the following command will delete the Kubernetes namespace named dev:

 $ 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.

Deleting multiple namespaces

To delete multiple namespaces at once, you can use the kubectl delete command as follows:

 $ kubectl delete namespace <namespace …>

Where:

• namespace … is a list of namespaces separated by a space character.

For example, the following command will delete the dev, qa, and staging namespaces all at once:

 $ kubectl delete namespace dev qa staging

Deleting all namespaces

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

 $ kubectl delete namespace --all

Deleting namespaces 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 -l flag (short for --label) as follows:

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

Where:

• label is the key of the label.
• value is the value associated with the label.

For example, the following command will remove all the namespaces with the label env=dev:

 $ 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 ! 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 app=production:

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

Simulating a namespace deletion

In Kubernetes, you can simulate the deletion of a namespace using the the --dry-run flag as follows:

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

Where:

• strategy can be one of none, client, or server.

For example, the following command will simulate the deletion of the dev namespace on the client side:

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

Client-side vs. server-side simulation

When using the --dry-run=client flag, Kubernetes simulates the deletion operation on the client side, which means that kubectl 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 --dry-run=server flag, Kubernetes simulates the deletion operation on the server side, which means that kubectl 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.

Specifying 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 --grace-period flag as follows:

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

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

For example, the following command will remove the dev namespace and wait 90 seconds before forcefully terminating any related resources:

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

Forcefully deleting a namespace

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

 $ kubectl delete namespace <namespace> --force

Note that the --force flag is mandatory when setting the grace period to 0:

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

Easily retrieve this command using Warp’s AI Command Search

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

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

Removing the finalizers attached to a namespace

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 kubectl patch 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

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

Permission denied

The kubectl 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

The kubectl command will output an error if the specified namespace doesn't exist.

For example, trying to remove the non-existent test namespace will result in the following error:

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