kubectl rollout: How to Manage, Roll Back, and Restart Deployments

kubectl rollout is the command that you use to control and inspect how Kubernetes rolls out changes to a workload. When you change a Deployment, Kubernetes replaces the old pods with new ones, and kubectl rollout is how you watch that process, pause it, roll it back, restart it, and see its history.

In this guide, you'll learn how Kubernetes actually runs a rollout under the hood, every kubectl rollout subcommand with examples, why rollouts get stuck and how to diagnose them, and the practices that make rollouts safe in production.

kubectl rollout undo

kubectl rollout undo rolls a workload back. With no arguments, it goes to the previous revision, and with --to-revision it goes to a specific one from the history:

kubectl rollout undo deployment/api
kubectl rollout undo deployment/api --to-revision=2

This works because Kubernetes still has the old ReplicaSet and simply scales it back up. A rollback is itself a rollout, so follow it with rollout status to confirm it finished.

One important limitation is that undo only restores the pod template. This includes the container image, environment variables, and resource settings. It does not undo changes made outside the pod template. For example, if the release also changed a ConfigMap, Secret, database schema, or external system, rolling back the Deployment does not reverse those changes.

For this reason, treat rollout undo as a quick recovery tool, not as your normal deployment strategy. It can quickly restore a previous pod version, but it cannot roll back everything that may have changed during a release.

kubectl rollout restart

kubectl rollout restart restarts all the pods in a workload without changing the image:

kubectl rollout restart deployment/api

The command adds a kubectl.kubernetes.io/restartedAt annotation with the current timestamp to the pod template, because this changes the pod template, and Kubernetes treats it as a normal rollout. It creates a new ReplicaSet and replaces the old pods gradually, following maxSurge, maxUnavailable, and readiness probes. With properly configured probes, this allows the application to restart without downtime.

A common use case is picking up changes that do not automatically restart pods. For example, when you update a ConfigMap or Secret that the application reads only at startup, existing pods continue using the old values. A rollout restart replaces those pods so they start with the new values.

A rollout restart is more controlled than manually deleting pods or scaling a Deployment to zero. Manually deleting pods replaces them, but does not give you the same controlled rollout process, and scaling to zero stops all pods before starting new ones, which causes downtime. A rollout restart replaces the pods gradually while following the Deployment's rollout settings.

kubectl rollout pause and resume

kubectl rollout pause stops a Deployment from acting on changes, and kubectl rollout resume lets it continue:

kubectl rollout pause deployment/api
kubectl rollout resume deployment/api

There are two ways this is useful. The first is batching several changes into a single rollout. If you pause first, then change the image, resources, and environment, and then resume, Kubernetes performs one rollout with all the changes instead of a separate rollout for each edit:

kubectl rollout pause deployment/api
kubectl set image deployment/api api=api:1.5.0
kubectl set resources deployment/api -c=api --limits=cpu=500m,memory=512Mi
kubectl rollout resume deployment/api

The second is pausing in the middle of a rollout to validate a partial canary. You start a rollout by changing the image, let a few new pods come up, then pause. Now a small share of traffic is on the new version while the rest stays on the old one, and you can watch its metrics and logs. If it looks healthy, resume to finish the rollout, and if it does not, undo to roll back. Remember that you cannot roll back a paused Deployment, so resume it before running undo.

Why rollouts get stuck and how to diagnose them?

A rollout gets stuck when new pods fail to become available, and the Deployment eventually reports ProgressDeadlineExceeded. The following are the most common causes:

a. Not enough cluster capacity for the surge pods: A rolling update creates extra pods (maxSurge) before removing old ones, so the rollout needs spare CPU and memory to schedule them. If the cluster has no room, the surge pods stay Pending, and the rollout cannot move. You have to check with kubectl get pods and kubectl describe pod on the pending pod, and see whether the Cluster Autoscaler can add a node.

b. Readiness probe failures and CrashLoopBackOff: If the new pods start but never pass their readiness probe, or crash and restart in a loop, they never count as available, and the rollout stalls. Read the new pod's logs with kubectl logs and its events with kubectl describe pod. This is where a misconfigured probe or a bad new image shows up.

c. OOMKills from under-sized memory requests and limits: If the new version needs more memory than its limit allows, the kernel kills each new pod as it starts, so the pod shows OOMKilled with exit code 137 and the rollout never completes. The pod's own logs are usually empty, because the container was killed rather than crashing, so the signal is in kubectl describe pod under the last state.

d. PodDisruptionBudgets do not block the rollout itself: A PodDisruptionBudget does not constrain a Deployment's rolling update. PDBs do not limit workload rolling updates because the rollout replaces pods directly rather than through the eviction API. What a PDB does constrain is voluntary evictions: node drains, Cluster Autoscaler scale-down, and similar. So a PDB can block a node drain that is happening at the same time as your rollout, and a badly set PDB (for example minAvailable equal to the replica count) can block drains entirely, but it is not what is holding up the rollout itself.

e. Horizontal Pod Autoscaler and replica conflicts: If an HPA manages a Deployment's replicas and you also hardcode replicas in the manifest, every kubectl apply resets the count to the manifest value until the HPA corrects it again. This can cause confusing scaling during a rollout. The fix is to leave replicas out of the manifest for any Deployment an HPA manages.

Most of these problems come back to resource sizing. Surge pods that cannot fit on the cluster and new pods that get OOMKilled both point to incorrect resource settings. This is where PerfectScale helps. Its Kubernetes governance platform watches how your workloads actually use CPU and memory and turns that into actionable, automated right-sizing recommendations that you can apply manually or autonomously. With requests and limits that match reality, your surge pods fit and your new pods have the memory they need, so rollouts finish cleanly instead of getting stuck. Teams like Paramount Pictures and Creditas use PerfectScale to keep their clusters efficient, and you can sign up or book a technical session.

Best practices for running kubectl rollout in production

Here are a few simple practices to keep production rollouts safe and smooth:

a. Right-size requests and limits before you roll out: You have to set accurate resource requests and limits before starting a rollout. This gives surge pods enough room to schedule and reduces the risk of new pods getting OOMKilled.

b. Check metrics and logs, not just rollout status: A successful rollout status only means the new pods became ready. It does not mean the application is working correctly. You should check error rates, latency, and logs after a rollout, especially when using a paused canary.

c. Set progressDeadlineSeconds and --timeout explicitly: You have to set a reasonable progressDeadlineSeconds so Kubernetes marks a stuck Deployment as failed. Use --timeout with rollout status so your pipeline stops waiting after a defined period.

d. Add a change-cause annotation to every change: You should set kubernetes.io/change-cause when making changes so rollout history clearly shows what changed in each revision. This makes it easier to choose the right revision during a rollback.

e. Keep revisionHistoryLimit high enough to roll back safely: The default of 10 is fine for most workloads, but if you deploy very frequently, make sure it still covers the revisions you might realistically need to return to.

f. Limit the blast radius by rolling out gradually: Avoid sending a risky change to every namespace or cluster at once. Roll it out in stages so you can catch problems early and stop before they affect everything.

g. Move from manual commands to GitOps and progressive delivery: kubectl rollout is useful for learning and managing rollouts manually. For larger production environments, tools such as Argo CD or Flux can manage deployments through GitOps, while Argo Rollouts or Flagger can automate canary and blue-green deployments.