The Kubernetes command-line tool, kubectl, provides a way to communicate with the Kubernetes cluster via the control plane to manage resources by creating, editing, and extracting details about specific resources. The tool comes with a number of commands that can be used to perform different tasks.
One of the commands associated with this tool is the
kubectl delete command. This command allows you to terminate running resources gracefully. Some of the use cases for the
kubectl delete command include the termination of running pods, deployments, services, StatefulSets, and many other resources.
In this guide, you'll learn how to appropriately use
kubectl delete to stop resources, and about the various parameters that this command offers. You’ll learn some best practices to guide you in the safe and correct use of this command.
What is kubectl delete?
kubectl delete offers you a way to gracefully shut down and terminate Kubernetes resources by their filenames or specific resource names. The graceful termination of resources using the
kubectl delete command is to be done with utmost discretion, because once the command has been run, there's no way to undo the deletion of the resource.
Kubernetes doesn't provide users with the ability to simply pause and resume resources. There are several ways to get around this limitation, one of which is to simply stop (delete) the desired resource to pause, and reapply the resource definition to the cluster to resume.
kubectl delete command is especially handy during clean up after the deployment of an application. During development, the creation and deployment of resources is a top concern, but the management of these resources sometimes falls to the wayside after deployment.
Some of these resource-management responsibilities involve deleting unused pods. These pods, while running and unused in the Kubernetes cluster, take up some of the node's resources, thereby limiting other, more important, running pods.
In some cases, a Kubernetes node needs to be shut down, and the Kubernetes deployments and services will need to be terminated. Another resource-management concern could be the deletion of StatefulSets that manage pods that rely on durable storage configurations, such as persistent volumes.
Using kubectl delete
Before you begin with this tutorial, you need to have an understanding of the following Kubernetes concepts:
- kubectl command-line tool
To get started with using
kubectl delete, you need to have a single-node Kubernetes cluster running with at least 4 GB of RAM available. You can create one locally with lightweight Kubernetes distributions, such as minikube, K3s, or MicroK8s, or you can provision one with a cloud provider such as Google Kubernetes Engine (GKE), Azure Kubernetes Service, or Amazon Elastic Kubernetes Service (EKS).
Kubectl delete basic use case
With your cluster set up, you can now begin with a basic use case of the
kubectl delete command.
Deploy a sample NGINX deployment by creating a file named
deployment.yaml, then adding the following code snippet:
You then run the configurations on your Kubernetes cluster with the
kubectl apply command:
The command above will create an NGINX deployment with a ReplicaSet and three NGINX pods deployed and running in the
default namespace in your Kubernetes cluster. To verify this, you can simply perform the
kubectl get pod command, and you'll get the following response:
Now that you've successfully deployed NGINX to your Kubernetes cluster, the next step is to clean up after the deployment.
If you perform the command
kubectl delete pods --all to delete all the NGINX pods in the default namespace, another set of pods will spring back up to replace the ones that were deleted. In order to prevent this from happening, you need to delete the deployment configuration using either the filename,
deployment.yaml, or the deployment name,
nginx-deployment, as configured in the
metadata section in the YAML code snippet above.
The NGINX Deployment can be deleted in two ways:
Once the deployment resource has been deleted, you shouldn't be able to see any pods, deployments, or ReplicaSets in the
default namespace. You'll see only a single Kubernetes service active when you perform the
kubectl get services command:
This will display the available services in the
Please note that depending on the type of Kubernetes distribution you are running, the output shown above may differ slightly.
Kubectl delete advanced use case
In the previous section, you created a simple NGINX deployment, then deleted it properly. In this section, you’ll look at a more advanced use case for the
kubectl delete command, and see the steps involved in applying the command.
In this example, you’ll deploy the popular WordPress CMS. To do this, you’ll create the WordPress service, the
wp-pv-claim PersistentVolumeClaim, and deploy the Wordpress app using the latest Docker Hub image.
Using your favorite text editor, create a file named
wordpress.yaml and paste in the following YAML code:
Apply the above configuration to your cluster by running the
kubectl apply command:
You’ll see output similar to the following:
Verify that the changes were executed correctly using the
kubectl get all command:
You should get output similar to this:
After verifying that the WordPress deployment was successful, you can proceed to cleanup.
As before, trying to delete the pods is futile, since the deployment specification will recreate them as many times as necessary. Fortunately, you only have to use one command to remove the newly created deployment, service, and PVC:
If you want, you can confirm the above output using the commands:
The output should be similar to the following:
No resources found in default namespace.
Another way to check that there are no remaining traces of WordPress is to use the
kubectl get all command again:
$ kubectl get all
As you can see, the
kubectl delete command is suitable for both simple and more advanced use cases.
However, note that this was possible because a single YAML file was used to configure all the moving parts. This may or may not be a good idea, as you could mistakenly delete even data stored on a persistent volume. This leads us to the next section, best practices.
A single misused
kubectl delete command can destroy a whole application and render it useless. There are no safety measures, such as prompts to ask if you truly want to delete the resource or not, attached to the command. Before you perform an operation with the
kubectl delete command, you need to know exactly what you want to delete and how you want it deleted.
You can use the
kubectl delete --help command to view a list of flags and options that can be applied.
Know when and how to use kubectl delete
Understanding when to delete Kubernetes resources requires that you know your application’s tolerance for the unavailability of one or more of the resources. If one of the resources is taken down, your application should still be able to function.
Similarly, knowing how to delete resources is essential to keeping your services and applications running. For instance, deleting resources with the
--force flag set to
true should be avoided, as this may result in resource inconsistency, leading to application runtime failure or data loss. Unless you're very certain that doing this won't create problems for your application, this should be used only as a last resort.
Don’t use kubectl delete unless absolutely needed
It is strongly advised that you use the
kubectl delete command sparingly, unless during important operations such as clean-up operations for resource optimization once all deployments are done with.
It's also advisable to hold off on deleting PersistentVolumeClaims until all necessary data is retrieved or copied, using the
kubectl cp command from the
mountPath on to your host machine.
In this article, you learned about the
kubectl delete command: what it is, the different use cases for it, and the recommended ways to use it.
kubectl delete command can be a great help when it comes to managing resources, but it's important to note that while it can prevent bottlenecks in your application,
kubectl delete can also break your application entirely if used carelessly.
Kubernetes deployments are best paired with a monitoring solution allows you to keep an eye on your resources, analyze the logs, and trace potential problems in your application, keeping you informed about your cluster's health and enabling you to better manage your resources.