How to restart a Kubernetes deployment rollout

A Kubernetes Deployment restart asks the Deployment controller to replace running pods without changing the image tag or rewriting the manifest. Operators use it after a dependent service recovers, after startup-loaded configuration changes, or when old pod connections need to drain through the Deployment rollout strategy.

kubectl rollout restart updates the Deployment's pod template metadata, which makes Kubernetes create a new ReplicaSet revision. The existing rollout strategy controls how many replacement pods can be created or made unavailable while the old pods are phased out.

Restart only the intended Deployment and namespace, then wait for rollout status before treating the application as refreshed. A completed restart reports the Deployment available again, and ReplicaSet output shows that a new revision owns the desired replicas.

1. Check that the target Deployment is available before restarting it.

   $ kubectl get deployment web --namespace team-a
   NAME   READY   UP-TO-DATE   AVAILABLE   AGE
   web    2/2     2            2           24s

   If this command reaches the wrong cluster or returns a permission error, fix the active context or namespace first.
   Related: How to check Kubernetes cluster access

2. Restart the Deployment rollout.

   $ kubectl rollout restart deployment/web --namespace team-a
   deployment.apps/web restarted

   This changes the pod template and starts a new rollout even when the container image remains the same.

3. Wait for the restarted rollout to finish.

   $ kubectl rollout status deployment/web --namespace team-a --timeout=180s
   Waiting for deployment "web" rollout to finish: 1 out of 2 new replicas have been updated...
   Waiting for deployment "web" rollout to finish: 1 old replicas are pending termination...
   deployment "web" successfully rolled out

   If the command times out or reports a progress deadline error, inspect the Deployment, ReplicaSet, pods, and recent events before retrying another restart.

4. Confirm the Deployment is available after the restart.

   $ kubectl get deployment web --namespace team-a
   NAME   READY   UP-TO-DATE   AVAILABLE   AGE
   web    2/2     2            2           25s

5. Check that rollout history has a new revision.

   $ kubectl rollout history deployment/web --namespace team-a
   deployment.apps/web
   REVISION  CHANGE-CAUSE
   1         <none>
   2         <none>

   CHANGE-CAUSE is <none> unless previous commands or manifests set the kubernetes.io/change-cause annotation.

6. Verify that the new ReplicaSet owns the desired replicas and the old ReplicaSet is scaled down.

   $ kubectl get replicasets --namespace team-a -l app=web
   NAME             DESIRED   CURRENT   READY   AGE
   web-6bbc9c7555   0         0         0       22s
   web-84f6dc8686   2         2         2       1s

   Use the Deployment's selector labels when the workload does not use app=web.