Face the Facts: There is no Kubectl Restart Pod Command. Here's What You Can Try Instead

Many Kubernetes operators search for a command like “kubectl restart pod” that will allow them to restart pods that are stuck in pending status, or otherwise making mischief. However, the sad truth is there is no such command in Kubernetes.

But don’t give up - there are a few great workarounds that will help you restart your misbehaving pods and get them back in business. I’ll show five of them.

What is kubectl?

Kubernetes is a closed system composed of master nodes and worker nodes. The only way to communicate with it is through the API server. The server is a key component of the Kubernetes control plane and exposes an HTTP REST API, which enables communication between users, clusters, and any external components.

An API is considered the front end or main user interface of the Kubernetes platform. Querying, updating, or managing the state of resources or objects in the Kubernetes platform is done by interacting with the Kubernetes API via kubectl - a client library - or by making REST requests directly.

kubectl is the most common way to make requests to the Kubernetes control plane, perform Kubernetes operations, control auto scaling operations, manage software deployment for containerized applications, inspect and manage cluster resources, and perform monitoring tasks and system logs.

Understanding Pod States

Kubernetes pods have five lifecycle states:

• Pending - this status indicates that one or more containers have yet to be created in the pod.
• Running - all containers are created and the pod is deployed to a node. At this point, containers are either running, starting, or restarting.
• Success - all containers in the Pod successfully terminated without restarting.
• Failed - all containers have exited and at least one containers has failed.
• Unknown - unable to get pod status.

When Do You Need to “Restart” a Pod?

A pod, which runs one or more containers, is the smallest unit managed within Kubernetes. It runs until replaced by a new deployment. Therefore, strictly speaking, the pod cannot be restarted and must be replaced.

However, a pod does need to be "restarted" in certain circumstances, such as when it is stuck in the "terminated" state, or when it has errors that cannot be corrected without a restart. There may be situations where you need to restart a pod after making configuration changes, such as modifying resource limits to limit the pod's memory limits, or changing the persistent volume storage the pod is using.

Because Kubernetes does not have a kubectl restart command for pods, there are several ways to "restart" a pod using kubectl - we’ll cover them below.

Restarting Kubernetes Pods Using kubectl

kubectl rollout restart

The rollout restart command can help you easily restart Kubernetes pods. When you use this option, the controller shuts down one pod at a time, using the ReplicaSet to add new pods until it replaces all the old pods with newer ones. This option is ideal for restarting pods without affecting or shutting down the application.

Here is the kubectl rollout restart command:

kubectl rollout restart deployment <deployment_name> -n <namespace>

kubectl delete pod

Kubernetes provides a declarative API, which means a pod API object uses the kubectl delete pod command. It automatically recreates the pod to keep it consistent with the expected one. However, if the ReplicaSet manages many pod objects, it will be difficult to delete each one manually. The following command can help you delete the entire ReplicaSet:

kubectl delete replicaset <name> -n <namespace>

Scaling the Number of Replicas

The scale command lets you change a failing pod’s number of allowed replicas. Note that if you set this value to zero, it turns the pod off:

kubectl scale deployment [deployment_name] --replicas=0

\You can restart the pod using the same command but setting the number of replicas to a value larger than zero:

kubectl scale deployment [deployment_name] --replicas=1

If you set the number of replicas to zero, Kubernetes destroys all replicas it does not need, while setting the number higher than zero tells Kubernetes to create new replicas with different names than the old ones. Use the kubectl get pods command to check the pods’ status and view the new names.

Changing Pod Annotations

Adding or modifying an annotation can force a pod to be replaced because Kubernetes must replace the pod to apply this change. Here is the command you can use to apply an annotation:

kubectl annotate pods my-pod app-version="2" --overwrite

The kubectl annotate command updates the ‘app-version’ annotation on ‘my-pod’, and the ‘--overwrite’ flag tells Kubectl to apply this change even when the annotation exists. Otherwise, you can add new annotations only as a safety measure to prevent accidental changes.

Alternatively, update a deployment’s environment variables to achieve a similar effect. Use this option if you already expose an app-version number, deploy date, or build ID in the environment.

kubectl set env deployment my-deployment APP_VERSION="2"

Using Environment Variables

You can change an environment variable to force Kubernetes pods to restart and sync with your changes. For example, try changing the container deployment date using the following command:

kubectl set env deployment [deployment_name] DEPLOY_DATE="$(date)"

I hope this helps! The next time you successfully restart your pod - coffee is on you.

**