Performing Rolling Updates

This page explains how to perform rolling updates for applications in
Google Kubernetes Engine.

Overview

You can perform a rolling update to update the images, configuration, labels,
annotations, and resource limits/requests of the workloads in your clusters.
Rolling updates incrementally replace your resource's Pods with new ones, which
are then scheduled on nodes with available resources. Rolling updates are
designed to update your workloads without downtime.

The following objects represent Kubernetes workloads. You can trigger a rolling
update on these workloads by updating their Pod Template:

DaemonSets

Deployments

StatefulSets

Each of these objects have a Pod template, represented by the spec: template
field in the object's manifest. The Pod template field contains a specification
for the Pods that the controller creates to realize the desired state or
behavior. You trigger an update rollout by updating the object's
spec: template.

Use the editor to make the desired changes to the object's labels or Pod
template.

Click Save.

Managing an update rollout

You can use
kubectl rollout
to inspect a rollout as it occurs, to pause and resume a rollout, to rollback an
update, and to view an object's rollout history.

Inspecting a rollout with kubectl rollout status

You can inspect the status of a rollout using the kubectl rollout status
command.

For example, you can inspect the nginx Deployment's rollout by running the
following command:

kubectl rollout status deployment nginx

The output is similar to the following:

Waiting for rollout to finish: 2 out of 3 new replicas have been updated...
deployment "nginx" successfully rolled out

After the rollout succeeds, run kubectl get deployment nginx to verify that
all of its Pods are running. The output is similar to the following:

NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE
nginx 3 3 3 3 36s

Pausing and resuming a rollout

Note: Currently, only Deployments support kubectl rollout pause and resume.

You can use kubectl rollout pause to pause a rollout.

For example, to pause the nginx Deployment's rollout, run the following
command:

kubectl rollout pause deployment nginx

To resume, run the following command:

kubectl rollout resume deployment nginx

Viewing rollout history with kubectl rollout history

You can use kubectl rollout history to view an object's rollout history.

For example, to view the nginx Deployment's rollout history, run the following
command:

kubectl rollout history deployment nginx

To see the history of the third revision, run the following
command:

kubectl rollout history deployment nginx --revision 3

Rollback an update with kubectl rollout undo

You can rollback an object's rollout using the kubectl rollout undo
command.

For example, to rollback to the previous version of the nginx Deployment, run
the following command:

kubectl rollout undo deployments nginx

Or, as another example, to rollback to the third revision of the Deployment, run
the following command:

kubectl rollout undo deployment nginx --to-revision 3

Considerations for StatefulSets and DaemonSets

StatefulSets since Kubernetes 1.7 and DaemonSets since Kubernetes 1.6 use an
update strategy to configure and disable automated rolling updates for
containers, labels, resource request/limits, and annotations for its Pods. The
update strategy is configured using the updateStrategy field.

The updateStrategy field accepts either OnDelete or RollingUpdate as
values.

OnDelete is the default behavior when updateStrategy is not
specified. OnDelete prevents the controller from automatically updating its
Pods. You must manually delete the Pods to cause the controller to create new
Pods that reflect your changes. OnDelete is useful if you prefer to manually
update Pods.

RollingUpdate implements automated, rolling updates for the Pods in the
StatefulSet. RollingUpdate causes the controller to delete and recreate each
of its Pod, and each Pod one at a time. It waits until an updated Pod is
running and ready before to updating its predecessor.

The StatefulSet controller updates all Pods in reverse ordinal order while
respecting the StatefulSet guarantees.

Using the RollingUpdate strategy

You can use the RollingUpdate strategy to automatically update all Pods in a
StatefulSet or DaemonSet.

For example, to patch the web StatefulSet to apply the RollingUpdate
strategy, run the following command:

Next, make a change to the StatefulSet's spec.template. For example, you can
use kubectl set to change the container image. In the following example, the
web StatefulSet is set to have its nginx container run the nginx-slim:0.7
image:

kubectl set image statefulset web nginx=nginx-slim:0.7

To check that the Pods in the StatefulSet running the nginx container are
updating, run the following command:

The Pods in the StatefulSet are updated in reverse ordinal order. The StatefulSet
controller terminates each Pod, and waits for it to transition to Running and
Ready prior to updating the next Pod.

Note: Although the controller does not proceed to update the next
Pod until its ordinal successor is Running and Ready, it restores any Pod
that fails during the update to its current version. Pods that have already
received the update are restored to the updated version, and Pods that have
not yet received the update are restored to the previous version.

Partitioning a RollingUpdate

You can specify a partition parameter a StatefulSet's RollingUpdate field.

If you specify a partition, all Pods with an ordinal number that is greater
than or equal to the partition value are updated. All Pods with an ordinal
number that is less than the partition value are not updated and, even if
they are deleted, are recreated at the previous version.

If a partition value is greater than its number of replicas, updates are not
propagated to its Pods. Partitioning is useful if you want to stage an update,
roll out a canary, or perform a phased roll out.

For example, to partition the web StatefulSet, run the following command:

This causes Pods with an ordinal number greater than or equal to 3 to be
updated.

DaemonSet's maxUnavailable parameter

DaemonSet's optional maxUnavailable parameter is a child of its
rollingUpdate field.

maxUnavailable determines the maximum number of DaemonSet Pods that can be
unavailable during updates. The default value, if omitted, is 1. The value
cannot be 0. The value can be an absolute number or a percentage.

Updating with the OnDelete strategy

If you prefer to update a StatefulSet or DaemonSet manually, you can omit the
updateStrategy field, which instructs the controller to use the OnDelete
strategy.

To update a controller that uses the OnDelete strategy, you must manually
delete its Pods after making changes to its Pod template.

For example, you can set the web StatefulSet to use the nginx-slim:0.7
image:

kubectl set image statefulset web nginx=nginx-slim:0.7

Then, to delete the first web Pod, run the following command:

kubectl delete pod web-0

To watch as the Pod is recreated by the StatefulSet and transitions to Running
and Ready, run the following command: