Kubernetes how-to
kubectl rollout restart: Restart Pods Without Downtime
kubectl rollout restart restarts the pods of a Deployment by running a rolling update on it. It does not change the image or the config, so it is the clean way to get pods to start again when they read configuration only at start-up. Each old pod is replaced according to the Deployment update strategy.
By Muhammad Soliman, Founder at SeaGit
·
Key takeaways
- kubectl rollout restart deployment/NAME replaces the pods one batch at a time. It is a rolling update with no image change.
- Pods are removed only as the replacements become ready, so the restart is zero downtime only if the new pods pass their readiness probe.
- Restarting a namespace or a label selector touches every matching Deployment. Check the scope before you press enter.
- To go back, use kubectl rollout undo. Undo returns the pod template to the previous revision; it does not undo a restart on its own.
What kubectl rollout restart actually does
A Deployment owns a ReplicaSet, and the ReplicaSet owns the pods. A restart is a change to the pod template that causes a new ReplicaSet and a new rollout. The controller then follows the Deployment strategy: it creates new pods, waits for them to become ready, and removes old pods within the limits of maxSurge and maxUnavailable.
Because the process is an ordinary rollout, you can watch it with the same commands you use for a deploy. You do not need to delete pods by hand, and you do not need to edit the manifest.
# Restart one Deployment in the prod namespace
kubectl rollout restart deployment/my-api -n prod
# Wait until the rollout finishes or fails
kubectl rollout status deployment/my-api -n prod
# Watch the pods being replaced
kubectl get pods -n prod -l app=my-api -wWhen a restart is the right fix
Restart when the pods are healthy but holding a stale value. The common cases are a rotated credential or a changed setting that the application reads once at start-up, a process that has leaked memory or file handles over days, and a cache that needs a clean start.
Do not use a restart to hide a crash loop. If the new pods fail the same way, the rollout stalls and the old pods keep serving, which is the protection you want, but the underlying fault is still there. Read the pod events first with kubectl describe pod.
Restart, edit, or delete?
| Goal | Use |
|---|---|
| Pick up a changed Secret or ConfigMap value | kubectl rollout restart, because the pod must start again |
| Ship a new image tag | Change the image in the manifest or kubectl set image; a restart is not needed |
| Replace one misbehaving pod | kubectl delete pod NAME; the ReplicaSet creates a replacement |
| Restart every workload in a namespace | kubectl rollout restart deployment -n NAMESPACE, after checking the list |
Scope: one Deployment, a namespace, or a label
The official examples cover three scopes. One Deployment by name, every Deployment in a namespace, and every Deployment matching a label selector. The namespace form is the risky one: it restarts all of them at once, and that can include services that have nothing to do with your change.
# Restart every Deployment in the test-namespace namespace
kubectl rollout restart deployment -n test-namespace
# Restart only the Deployments labelled app=nginx
kubectl rollout restart deployment --selector=app=nginx -n prod
# Restart a DaemonSet
kubectl rollout restart daemonset/log-agent -n kube-system- A label selector is safer than a namespace-wide restart, but check that the label matches only what you intend.
- A rollout on a workload with one replica and maxUnavailable of 1 can take the only pod down before the new one is ready. Set maxUnavailable to 0 and maxSurge to 1 for single-replica services that must stay up.
- A restart with a failing readiness probe does not take traffic away from the old pods, because old pods are kept until replacements are ready.
Verify the restart and undo it if it goes wrong
A restart creates a new revision of the Deployment. You can list the revisions and roll back to the previous one. Undo only reverts the pod template, so it returns the pods to the template of the previous revision. It does not restore a pod that was deleted outside a rollout.
# Revisions created by restarts and updates
kubectl rollout history deployment/my-api -n prod
# Roll back to the previous revision
kubectl rollout undo deployment/my-api -n prod
# Or to a specific revision
kubectl rollout undo deployment/my-api -n prod --to-revision=3Common failure: the rollout never finishes
If rollout status waits forever, the new pods are not becoming ready. The events show why. The usual causes are a readiness probe that points at the wrong port, a container that exits on start, or a resource request that no node can satisfy.
kubectl get rs -n prod -l app=my-api
kubectl describe pod -n prod -l app=my-api | sed -n '/Events:/,$p'