Versioning and upgrades

Note: The Kubernetes API is versioned separately from Kubernetes itself. Refer to the Kubernetes API documentation for information about Kubernetes API versioning.

This page explains versioning and automatic upgrades in Google Kubernetes Engine (GKE).

Rollout schedule

GKE follows a predictable multi-day rollout schedule for making new versions available, as well as auto-upgrading cluster control planes (masters) and nodes. The rollout generally spans four or more days, and includes a buffer of time to observe and monitor for problems. Zones and regions are updated in a predictable order.

Note: This table may temporarily exclude recently-added zones or regions.

Day	Available zones	Available regions
Day 1	europe-west2-a, us-east1-d	europe-west3, us-east1
Day 2	asia-east1-a, asia-east2-c, asia-northeast1-a, asia-northeast2-c, asia-northeast3-c, asia-south1-a, asia-southeast1-a, asia-southeast2-c, australia-southeast1-a, europe-north1-c, europe-west1-c, europe-west3-a, europe-west4-a, europe-west6-c, northamerica-northeast1-c, southamerica-east1-a, us-central1-b, us-east4-b, us-west1-a, us-west2-c, us-west3-c, us-west4-c	asia-east1, asia-southeast1, europe-west6, northamerica-northeast1, us-east4, us-west2
Day 3	asia-east1-c, asia-east2-b, asia-northeast1-b, asia-northeast2-b, asia-northeast3-b, asia-south1-b, asia-southeast1-b, asia-southeast2-b, australia-southeast1-b, europe-north1-b, europe-west1-b, europe-west2-b, europe-west3-b, europe-west4-c, europe-west6-b, northamerica-northeast1-b, southamerica-east1-b, us-central1-f, us-east1-c, us-east4-c, us-west1-b, us-west2-b, us-west3-b, us-west4-b	asia-east2, asia-northeast1, australia-southeast1, europe-west1, europe-west2, southamerica-east1, us-west1
Day 4	asia-east1-b, asia-east2-a, asia-northeast1-c, asia-northeast2-a, asia-northeast3-a, asia-south1-c, asia-southeast1-c, asia-southeast2-a, australia-southeast1-c, europe-north1-a, europe-west1-d, europe-west2-c, europe-west3-c, europe-west4-b, europe-west6-a, northamerica-northeast1-a, southamerica-east1-c, us-central1-a, us-central1-c, us-east1-b, us-east4-a, us-west1-c, us-west2-a, us-west3-a, us-west4-a	asia-northeast2, asia-northeast3, asia-south1, asia-southeast2, europe-north1, europe-west4, us-central1, us-west3, us-west4

Versioning

GKE clusters support running Kubernetes versions from any supported minor release. At least two, if not three, minor versions are available at any given time. However, subsequent intermediate releases might change what versions are available for new clusters.

Versioning scheme

Minor versions (1.X)

Kubernetes releases a new minor version approximately every three months. A minor version increments the Kubernetes version from 1.X to 1.X+1; for example, Kubernetes 1.10 is the minor release that follows Kubernetes 1.9.

Patch releases (1.X.Y)

New Kubernetes patch releases (such as 1.9.7) for use with GKE typically become available each week. Patch releases are rolled out to each compute zone incrementally.

Security updates and bug fixes (1.X.Y-gke.N)

A patch release with a -gke.N suffix (such as 1.9.7-gke.N) includes security updates and/or bug fixes for GKE alongside the open-source upstream Kubernetes software. These updates or fixes are required for compatibility and interoperability with Google Cloud.

Checking available and default versions

For information on available versions, see the GKE release notes.

You can also check which Kubernetes versions are available and default in a given zone from Google Cloud Console or by using the gcloud command-line tool.

gcloud

To see which versions are available and default, run the following command:

gcloud container get-server-config --zone compute-zone

where compute-zone is your cluster's compute zone, such as us-central1-a.

Note: If you run this command before a version rollout has completed, the command's output might not be accurate for your zone.

Console

To see which versions are available and default, perform the following steps:

1. Visit the GKE menu in Cloud Console.

   Visit the GKE menu

2. Click Create cluster.

3. Click the Master version drop-down menu. All currently available versions are listed. The default version is automatically selected.

4. From Node pools, under the default pool, click Advanced edit.

5. Click the Node version drop-down menu. All currently available versions are listed. The default version for nodes matches the current default version for cluster control planes.

Note: If you use Cloud Console to create a cluster before a version rollout has completed, the lists of available versions might not be accurate for your zone.

If you expect a version to be available to you and it isn't, check the Rollout schedule for your cluster's zone or region.

Specifying cluster version

When you create or upgrade a cluster using gcloud, you can specify a cluster version using the --cluster-version flag. You can use a specific version, such as 1.9.7-gke.N. You can also use a version alias:

• latest: Specifies the highest supported Kubernetes version currently available on GKE in the cluster's zone or region.
• 1.X: Specifies the highest valid patch+gke.N patch release in the 1.X minor version
• 1.X.Y: Specifies the highest valid gke.N patch in the 1.X.Y patch release.
• -: For cluster control planes, specifies the default Kubernetes version for control planes. For node upgrades, specifies the version that the cluster control plane is currently running.

Creating or upgrading a cluster by specifying the version as latest does not provide automatic upgrades. Enable automatic node upgrades to ensure that the nodes in your cluster up to date with the latest stable version.

Specifying node version

When you create or upgrade a node pool, you can specify its version. By default, nodes run the same version of GKE as the control plane. Nodes can be no more than two minor versions older than control planes.

With rare exceptions, node versions remain available even if the cluster version is no longer available.

Upgrades

New GKE clusters are created with a default version, a stable release of a recent Kubernetes minor version or patch release. Versions newer than the default are also generally available on a weekly basis.

Automatic cluster control plane version upgrades

Periodically, the GKE team performs automatic upgrades of your cluster control plane on your behalf. Control planes are upgraded to newer stable versions of Kubernetes. Automatic upgrades are typically performed in stages over multiple weeks.

You can also manually initiate a control plane upgrade to a version newer than the default.

To see when the control plane was recently updated, run the following command:

gcloud container operations list --filter="TYPE:UPGRADE_MASTER AND TARGET:cluster-name"

Replace cluster-name with the name of your cluster.

Automatic node version upgrades

Nodes created using Cloud Console are automatically upgraded by default. If you want nodes created with the gcloud command line tool or the GKE API to be upgraded automatically, you can enable automatic node upgrades.

Consider the following when choosing the version for your GKE nodes:

• Nodes must run a version that is currently available.
• Nodes cannot run a version newer than the cluster's current control plane version.
• Nodes cannot be more than two minor versions behind the control plane version.