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.

Related: How to update a Kubernetes Deployment image
Related: How to roll back a Kubernetes Deployment

Steps to restart a Kubernetes Deployment rollout:

  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.