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.

The Pod template includes the following fields:

• containers
• containers: image
• metadata: labels
• volumes

To learn more about the Pod template, refer to the PodTemplateSpec documentation.

Scaling a resource or updating fields outside of the Pod template does not trigger a rollout.

Before you begin

To prepare for this task, perform the following steps:

• Ensure that you have enabled the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• Ensure that you have installed the Cloud SDK.
• Set your default project ID:

  gcloud config set project [PROJECT_ID]

• If you are working with zonal clusters, set your default compute zone:

  gcloud config set compute/zone [COMPUTE_ZONE]

• If you are working with regional clusters, set your default compute region:

  gcloud config set compute/region [COMPUTE_REGION]

• Update gcloud to the latest version:

  gcloud components update

Note: You can override these default settings in gcloud commands using the --project, --zone, and --region operational flags.

Updating an application

The following section explains how you can update an application using Google Cloud Platform Console or kubectl.

kubectl set

You can use kubectl set to make changes to an object's image, resources (compute resource such as CPU and memory), or selector fields.

For example, to update a Deployment from nginx version 1.7.9 to 1.9.1, run the following command:

kubectl set image deployment nginx nginx=nginx:1.9.1

The kubectl set image command updates the nginx image of the Deployment's Pods one at a time.

As another example, to set the resource requests and limits of the Deployment:

kubectl set resources deployment nginx --limits cpu=200m,memory=512Mi --requests cpu=100m,memory=256Mi

Or, to remove the Deployment's resource requests:

kubectl set resources deployment nginx --limits cpu=0,memory=0 --requests cpu=0,memory=0

kubectl apply

You can use kubectl apply to update an object by applying a new or updated manifest file.

Note: To update a resource with kubectl apply, the resource would need to have been created using either kubectl apply or kubectl create --save-config.

To apply a new manifest file, run the following command:

kubectl apply -f [MANIFEST]

where [MANIFEST] is the updated manifest file.

Console

To edit the live configuration of an application, perform the following steps:

1. Visit the Google Kubernetes Engine Workloads menu in GCP Console.

   Visit the Workloads menu

2. Select the desired workload.

3. Click Edit.

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

5. 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:

kubectl patch statefulset web -p '{"spec":{"updateStrategy":{"type":"RollingUpdate"}}}'

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:

kubectl get pods -l app=nginx -w

The output is similar to the following:

NAME      READY     STATUS    RESTARTS   AGE
web-0     1/1       Running   0          7m
web-1     1/1       Running   0          7m
web-2     1/1       Running   0          8m
web-2     1/1       Terminating   0         8m
web-2     1/1       Terminating   0         8m
web-2     0/1       Terminating   0         8m
web-2     0/1       Terminating   0         8m
web-2     0/1       Terminating   0         8m
web-2     0/1       Terminating   0         8m
web-2     0/1       Pending   0         0s
web-2     0/1       Pending   0         0s
web-2     0/1       ContainerCreating   0         0s
web-2     1/1       Running   0         19s
web-1     1/1       Terminating   0         8m
web-1     0/1       Terminating   0         8m
web-1     0/1       Terminating   0         8m
web-1     0/1       Terminating   0         8m
web-1     0/1       Pending   0         0s
web-1     0/1       Pending   0         0s
web-1     0/1       ContainerCreating   0         0s
web-1     1/1       Running   0         6s
web-0     1/1       Terminating   0         7m
web-0     1/1       Terminating   0         7m
web-0     0/1       Terminating   0         7m
web-0     0/1       Terminating   0         7m
web-0     0/1       Terminating   0         7m
web-0     0/1       Terminating   0         7m
web-0     0/1       Pending   0         0s
web-0     0/1       Pending   0         0s
web-0     0/1       ContainerCreating   0         0s
web-0     1/1       Running   0         10s

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:

kubectl patch statefulset web -p '{"spec":{"updateStrategy":{"type":"RollingUpdate","rollingUpdate":{"partition":3}}}}'

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:

kubectl get pod web-0 -w

The output of this command is similar to the following:

NAME      READY     STATUS               RESTARTS   AGE
web-0     1/1       Running              0          54s
web-0     1/1       Terminating          0         1m
web-0     0/1       Terminating          0         1m
web-0     0/1       Terminating          0         1m
web-0     0/1       Terminating          0         1m
web-0     0/1       Pending              0         0s
web-0     0/1       Pending              0         0s
web-0     0/1       ContainerCreating    0         0s
web-0     1/1       Running              0         3s

Updating a Job

When you update a Job's configuration, the new Job and its Pods run with the new configuration. After updating a Job, you must manually delete the old Job and its Pods, if desired.

To delete a Job and all of its pods, run the following command:

kubectl delete job my-job

To delete a Job but keep its Pods running, specify the --cascade false flag:

kubectl delete job my-job --cascade false

You can also run kubectl describe deployment nginx, which yields even more information about the Deployment.

What's next

• Learn about upgrading your cluster.