How to Delete Kubernetes Pods with kubectl

Introduction

Kubernetes automates most management tasks related to pods, such as creation, scheduling, health checks, and deletion. However, administrators may have to use the kubectl interface to remove pods when maintaining a node or manually scaling a cluster.

This tutorial shows how to delete Kubernetes pods using kubectl. Learn how to remove all the pods from a node and delete individual pods.

Prerequisites

• Administrative access to the cluster.
• kubectl installed.

Delete Pods with kubectl

Depending on the scenario, a user may need to remove a misbehaving pod or evict an entire cluster node for troubleshooting or maintenance. The following sections present two ways of deleting pods with kubectl and provide instructions for avoiding the most common errors.

Delete Single Pod

Use the kubectl delete command to remove a single pod from a node:

1. Obtain the pod's full name by typing the following command:

kubectl get pods

A list of available pods appears. Find the pod you want to delete and make a note of its name.

2. Enter the command below to delete the pod:

kubectl delete pod [pod-name]

The output confirms the pod deletion.

When Kubernetes deletes the pod, it automatically replaces it with a new pod that uses the same specifications. Recheck the pod list:

kubectl get pods

The list shows the newly created pod.

 kubectl scale deployment [deployment-name] --replicas=[number]

Delete All Pods From Node

Drain a node by removing all the pods and preventing new pods from spawning. kubectl has the drain command that performs both actions on a specified node.

Follow the steps below to delete all the pods from a node.

1. Display the list of the available nodes:

kubectl get nodes

The output shows a cluster of three nodes with the Ready status.

2. Use the -o option with the wide argument to see a detailed list of the pods in the cluster:

kubectl get pods -o wide

The detailed pod list contains a NODE column, which shows the node that hosts each pod. The example output below shows three running pods on the test-node-1 worker node.

3. Use the kubectl drain command to evict the pods from the node.

kubectl drain [node-name]

The output shows the command performing two actions:

• Cordoning the node. This action prevents new pods from spawning on the machine.
• Draining the node. Draining removes the currently present pods.

4. Test the operation by checking the list of available nodes in the cluster.

kubectl get nodes

The drained node shows the SchedulingDisabled status.

kubectl cordon [node-name]

Troubleshooting Errors

When attempting to evict pods from a node, you may encounter errors. Below is the list of the most common errors and tips for resolving them.

Cannot delete DaemonSet-managed Pods

You cannot automatically evict pods managed by a DaemonSet. If the node you attempt to drain contains such pods, use the --ignore-daemonsets option to override the error.

kubectl drain [node-name] --ignore-daemonsets

Cannot delete Pods with local storage

If a pod connects to a persistent volume, the storage data may prevent pod eviction.

To avoid this error, add the --delete-emptydir-data option:

kubectl drain [node-name] --delete-emptydir-data

Cannot evict Pod as it would violate the Pod's disruption budget.

If your application has a Pod Disruption Budget (PDB), it limits the number of pods that can be down simultaneously. PDB may cause an error when evicting a node because the number of removed pods exceeds the set policy.

Type the following command to see the PDBs currently enforced on the system:

kubectl get pdb -A

The output shows the available PDBs and their policies. For example, the picture below shows a cluster with one PDB named test-pdb, which imposes a requirement of at least one running pod.

Change the PDB policy that prevents the node from draining, or delete it with kubectl:

kubectl delete pdb [policy-name]

Delete Pods Forcefully

If a pod cannot be removed with standard methods, try the steps below:

1. Use the following kubectl delete command:

kubectl delete pods [pod-name] --grace-period=0 --force

The --grace-period option set to zero removes the waiting time for the pod removal. The --force option ignores warnings and errors. The output shows the pod was deleted successfully.

If a pod remains on the pod list after deletion, run the following command to remove it:

kubectl patch pod [pod-name] -p '{"metadata":{"finalizers":null}}'

Allow Pods Back Onto Nodes

When you execute the drain command on a node, Kubernetes automatically cordons the node and prevents any future pods from scheduling. When you are ready to send pods to the node again, make the pod schedulable by entering:

kubectl uncordon [node-name]

The node can now receive new pods.

Conclusion

After reading this article, you should know how to use the kubectl CLI to remove pods from a cluster node in Kubernetes. The tutorial covered the procedures to remove single pods and drain entire nodes.

Next, learn about Horizontal Pod Scaling (HPA), an essential Kubernetes feature for controlling resource utilization.