When you build a system with Kubernetes, you will use a pod as a fundamental item. But sometimes, your pod is stuck, or you need to restart the pod to debug manually. Generally, you will think of the command “kubectrl restart pod,” but we don’t have this command in Kubernetes. So, how can we do that? Let’s move to the following sections for more details.
What is a pod?
In Kubernetes, a pod is the smallest execution unit. Pods may comprise a single or multiple containers that share the same resources within the Pod Storage, Network, or namespaces. Pods typically have a one-to-one mapping with containers, but in more advanced situations, we may run multiple containers in a Pod. Kubernetes can use replication controllers to scale the application horizontally when containers are grouped into pods. For instance, if a single pod is overloaded, Kubernetes could automatically replicate and deploy it in a cluster.
Why Restarting a Pod is Necessary
- Applying configuration changes → If there are updates on the pod’s configuration (configmaps, secrets, environment variables), in some cases, you may need to manually restart the pod for the changes to take effect.
- Debugging applications → Sometimes, if your application is not running correctly or you are just experiencing some issues with it, a good practice is to restart the underlying pods to reset their state and simplify troubleshooting.
- Pod stuck in a terminating state → In this case, usually, a delete and a recreation would do the trick in most cases. However, there are some cases where a node is taken out of service, and the pods cannot be evicted from it, in which a restart will help address the issue.
- OOM → If a pod is terminated with an Out Of Memory Error (OOM), you will need to restart the pod after making changes to the resource specifications. This may be solved automatically if the pod’s restart policy allows it.
- Forcing a new image pull → To ensure a pod is using the latest version of an image, if you are using the latest tag (which is not a best practice), you need to manually restart the pod to force a new image pull. Of course, if you change the image parameter in the configuration because you’ve released a new image and want to take advantage of that, a restart will still be required.
- Resource contention → If a pod is consuming excessive resources, causing performance issues, or affecting other workflows, restarting the pod may release those resources and mitigate the problem. This usually occurs when you are not using memory and CPU restrictions.
Pod Status
A pod has five possible statuses:
- Pending: This state shows that at least one pod container has not yet been created.
- Running: All containers have been created, and the pod has been bound to a Node. At this point, the containers are running or are being started or restarted.
- Succeeded: All containers in the pod have been successfully terminated and will not be restarted.
- Failed: All containers have been terminated, and at least one failed. The failed container exists in a non-zero state.
- Unknown: The status of the pod cannot be obtained.
If you notice a pod in an undesirable state where the status is showing as ‘error,’ you might try a ‘restart’ as part of your troubleshooting to get things back to normal operations. You may also see the status CrashLoopBackOff , the default when encountering an error, and K8S tries to restart the pod automatically.
There is no kubectl restart [podname] command for use with K8S (with Docker, you can use docker restart [container_id] ), so there are a few different ways to achieve a pod ‘restart’ with kubectl.
The difference between restarting a pod and recreating it.
| Action | Description | Effect on Pod ID | Effect on Pod Status | Effect on Pod Data |
|---|---|---|---|---|
| Restarting Pod | Restarting the Pod typically refers to restarting the container inside the Pod. | Since the Pod is just restarted rather than deleted and regenerated, the pod ID doesn’t change. | The Pod’s status changes from running to terminating and then back to running. | The pod data is kept intact unless the pod specification or image has changed. |
| Recreating Pod | When a pod is recreated, the old one must be removed, and a new one must be created. | When a new pod is formed and the old one is destroyed, the pod ID changes. | The pod status changes between Running, Terminating, and Pending before returning to Running. | It is lost unless the pod data is saved in an external source or a persistent volume. |
How to use kubectl restart pod
Kubectl Restart Pod – Method 1
kubectl rollout restart
This method is the recommended first port of call as it will not introduce downtime as pods will be functioning. A rollout restart will kill one pod at a time, then new pods will be scaled up.
kubectl rollout restart deployment <deployment_name> -n <namespace>
Kubectl Restart Pod – Method 2
kubectl scale
This method will introduce an outage and is not recommended. If downtime is not an issue, this method can be used as it can be a quicker alternative to the kubectl rollout restart method (your pod may have to run through a lengthy Continuous Integration / Continuous Deployment Process before redeployment).
If no YAML file is associated with the deployment, you can set the number of replicas to 0.
kubectl scale deployment <deployment name> -n <namespace> --replicas=0
This terminates the pods. Once scaling is complete, the replicas can be scaled back up as needed (to at least 1):
kubectl scale deployment <deployment name> -n <namespace> --replicas=3
Pod status can be checked during the scaling using:
kubectl get pods -n <namespace>
Kubectl Restart Pod – Method 3
kubectl delete pod and kubectl delete replicaset
Each pod can be deleted individually if required:
kubectl delete pod <pod_name> -n <namespace>
Doing this will cause the pod to be recreated because K8S is declarative; it will create a new pod based on the specified configuration.
However, this is not a practical approach where many pods are running. Where lots of pods have the same label, however, you could use that to select multiple pods at once:
kubectl delete pod -l “app:myapp” -n <namespace>
Another approach is if there are lots of pods, then ReplicaSet can be deleted instead:
kubectl delete replicaset <name> -n <namespace>
Kubectl Restart Pod – Method 4
kubectl set env
Setting or changing an environment variable associated with the pod will cause it to restart to take the change. The example below sets the environment variable DEPLOY_DATE to the date specified, causing the pod to restart.
kubectl set env deployment <deployment name> -n <namespace> DEPLOY_DATE="$(date)"