How to Delete Kubernetes Pods with kubectl

May 23, 2023

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.

How to delete Kubernetes pods with kubectl.

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.

Viewing the pods running in the cluster.

2. Enter the command below to delete the pod:

kubectl delete pod [pod-name]

The output confirms the pod deletion.

Deleting a pod using kubectl delete.

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.

Viewing the available pods after deletion of a pod.

Note: Deleting pods cannot change the number of running pod replicas. Instead, change it by modifying the deployment YAML file, or use kubectl scale:

 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.

Viewing available cluster nodes.

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.

Viewing a detailed list of pods.

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.
Draining a node with kubectl.

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

kubectl get nodes

The drained node shows the SchedulingDisabled status.

Viewing the list of nodes after draining a node.

Note: The kubectl cordon command allows you to cordon a node without draining it:

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.

Viewing pod disruption policies on a cluster.

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.

Force deleting a pod with kubectl.

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]
Uncordoning a node with kubectl.

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.

Was this article helpful?
YesNo
Marko Aleksic
Marko Aleksić is a Technical Writer at phoenixNAP. His innate curiosity regarding all things IT, combined with over a decade long background in writing, teaching and working in IT-related fields, led him to technical writing, where he has an opportunity to employ his skills and make technology less daunting to everyone.
Next you should read
Kubernetes Objects Guide
August 11, 2022

This guide will provide a detailed overview of Kubernetes objects, analyze their structure, and offer helpful object management tips.
Read more
How to Run Kubernetes Jobs
June 30, 2022

Certain K8s tasks require pods to terminate after completion. To perform those tasks, administrators use specific workload resources called jobs.
Read more
How to Restart Kubernetes Pods
November 27, 2023

If a container-related error pops up, you need a quick and easy way to fix the problem. This tutorial will explain how to restart pods in Kubernetes.
Read more
What is Kubernetes HPA?
July 14, 2022

Dynamic pod scaling is a Kubernetes feature that makes it easy to control resource utilization and ensure that a specific number...
Read more