Use release channels

Autopilot Standard

---

As a platform administrator, you can choose a specific release channel for your cluster to ensure that GKE automatically upgrades your cluster to versions with your chosen balance between feature availability and stability. To learn more about release channels, see About release channels.

GKE enrolls all Autopilot clusters in a release channel, and enrolls Standard clusters, by default, in a release channel. For all cluster modes, you can choose a specific release channel. With Standard clusters, you can choose to not enroll your cluster in a release channel.

This page explains how to take the following actions related to release channels:

• Enroll a cluster in a specific release channel.
• Find a cluster's release channel.
• View the default and available versions for release channels.
• Change a cluster's release channel.
• Unenroll your cluster from release channels.

Before you begin

Before you start, make sure you have performed the following tasks:

• Enable the Google Kubernetes Engine API.
Enable Google Kubernetes Engine API
• If you want to use the Google Cloud CLI for this task, install and then initialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running gcloud components update.
  Note: For existing gcloud CLI installations, make sure to set the compute/region and compute/zone properties. By setting default locations, you can avoid errors in gcloud CLI like the following: One of [--zone, --region] must be supplied: Please specify location.

Enroll a cluster in a release channel

This section shows you how to select a specific release channel for new clusters, or for existing clusters that didn't previously use a release channel. You can also change the release channel for an existing cluster that is already enrolled in a release channel.

Enroll a new cluster in a specific release channel

All clusters are enrolled in the Regular release channel, by default. You can choose a specific release channel for a cluster when you create the cluster, or change the release channel after the cluster is created. Autopilot clusters must be enrolled in a release channel. Standard clusters can be enrolled or unenrolled in a release channel.

You can create and enroll a new cluster in a specific release channel using the Google Cloud console or the gcloud CLI.

Console

Create a cluster with the following steps, depending on the cluster mode:

• For Autopilot clusters:

  1. On the Autopilot cluster creation page, from the navigation pane, click Advanced settings:

     Create an Autopilot cluster

  2. In the Release channel drop-down list, select a release channel to enroll the cluster in, or leave the default value of Regular channel.

• For Standard clusters:

  1. On the Standard cluster creation page, in the Cluster basics section, navigate to the Release channel subsection:

     Create a Kubernetes cluster

  2. In the Release channel drop-down list, select a release channel to enroll the cluster in, or leave the default value of Regular channel.

  Note: Node auto-upgrade and node auto-repair are enabled by default. Node auto-upgrade can't be disabled for a cluster subscribed to a release channel, however you can use maintenance windows and exclusions to control the timing and scope of automatic upgrades. Node auto-repair can be disabled, however we recommend keeping the default configuration.

gcloud

To create and enroll an Autopilot cluster in a specific release channel, run the following command:

gcloud container clusters create-auto CLUSTER_NAME \
    --location=COMPUTE_LOCATION
    --release-channel=CHANNEL

To create and enroll a Standard cluster in a specific release channel, run the following command:

gcloud container clusters create CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --release-channel=CHANNEL

Replace the following:

• CLUSTER_NAME: the name of your new cluster.
• CLUSTER_LOCATION: the Compute Engine location for the new cluster.
• CHANNEL: the type of release channel: one of rapid, regular, or stable.

For a list of other options that you can specify, see the gcloud container clusters create-auto and gcloud container clusters create reference documentation.

You can also create a cluster with a specific version using the --cluster-version flag. If you don't specify a release channel, GKE enrolls your cluster in the most mature release channel where that version is available.

Or, if you don't specify the release channel or cluster version, the cluster defaults to the Regular release channel on the default version.

Enroll an existing cluster

You can enroll an existing cluster in a release channel, as long as the cluster's control plane minor version is available in the target release channel. To check if your cluster's control plane minor version is available in the target release channel, view the default and available versions for release channels. To learn more about aligning your cluster's control plane version with the available versions for your target release channel, see Select a new release channel.

GKE doesn't require any downtime to change the release channel enrollment of a cluster. However, GKE might have different automatic upgrades available in a different release channel, meaning that, after the change, GKE might automatically upgrade the cluster. We recommend using maintenance windows and exclusions to control the timing of upgrades.

To enroll, update the cluster release channel to the target CHANNEL.

Note: GKE doesn't immediately upgrade the cluster control plane and nodes to the minor version's auto-upgrade target in that release channel when enrolling. Instead, they are gradually upgraded by the GKE auto-upgrade process.

Find your cluster's release channel

You can determine your cluster's release channel using the Google Cloud console or the gcloud CLI.

Console

1. Go to the Google Kubernetes Engine page in the Google Cloud console.

   Go to Google Kubernetes Engine

2. Click the name of the cluster you want to inspect.

3. Under Cluster basics, check the value in the Release Channel field (for example, Regular Channel).

If the value is None, the cluster isn't enrolled in a release channel.

gcloud

gcloud container clusters describe CLUSTER_NAME \
    --location=COMPUTE_LOCATION --format="value(releaseChannel.channel)"

Replace the following:

• CLUSTER_NAME: the name of your cluster.
• COMPUTE_LOCATION: A Compute Engine location for your cluster.

If the output is empty, the cluster isn't enrolled in a release channel.

View the default and available versions for release channels

To check what versions are available in a specific release channel with the Google Cloud console or gcloud CLI, follow the instructions to check available and default versions.

Change your cluster's release channel

You can change the release channel of your cluster if the control plane's minor version is available in the target release channel. You might need to upgrade or downgrade your cluster's control plane to an available version.

To check if your cluster's control plane version is available in the target release channel, view the default and available versions for release channels. The version must be available in the target channel.

• If your cluster's control plane version is already available in the target release channel, you can select the new release channel.
• If your cluster's control plane version is not available in the target release channel, you can upgrade the cluster's control plane to an available version. Alternatively, if the target channel only has earlier versions available, you can downgrade the cluster, provided that the target version is an earlier patch release from the same minor version.

To select a new release channel, update the cluster release channel to the target CHANNEL. If you want to temporarily prevent the cluster from being automatically upgraded when you select the new channel, configure a maintenance exclusion before selecting the new channel.

If you can't select the target release channel because your cluster is running a version that is not available in that release channel, you can do the following:

1. Configure a maintenance exclusion with a scope of "No minor upgrades".
2. Wait for the target release channel to make available the Kubernetes minor version of your cluster.
3. Enroll the existing cluster in the target release channel.

Alternatively, you can create a new cluster in the target channel and migrate your workloads.

Update the cluster release channel

You can change your cluster's release channel using the Google Cloud console or gcloud CLI.

Console

1. Go to the Google Kubernetes Engine page in the Google Cloud console.

   Go to Google Kubernetes Engine

2. Click the name of the cluster you want to inspect.

3. Under Cluster basics, in the Release channel field, click .

4. In the Release channel drop-down, select the target release channel.

5. Read and acknowledge the warning by selecting I understand there may be downtime during version upgrades.

6. Click Save Changes.

gcloud

Change the release channel property of an existing cluster:

gcloud container clusters update CLUSTER_NAME \
  --release-channel CHANNEL

Replace the following:

• CLUSTER_NAME: the name of your cluster.
• CHANNEL: the target release channel, which can be one of rapid, regular, stable, and, for Standard only, None.

Unsubscribe from a release channel

While you can unsubscribe your Standard cluster from a release channel, we strongly recommend that you review when to not enroll your cluster in a release channel to ensure that you understand the tradeoffs between enrolling and not enrolling your cluster in a release channel.

You can perform this action with the Google Cloud console, the gcloud CLI, or the Kubernetes Engine API. You can also specify that you don't want to enroll your Standard cluster in a release channel during cluster creation. You can't unsubscribe Autopilot clusters from a release channel.

Console

1. Go to the Google Kubernetes Engine page in the Google Cloud console.

   Go to Google Kubernetes Engine

2. Click the name of the cluster you want to inspect.

3. Under Cluster basics, in the Release channel field, click .

4. Select the Static version from the drop-down menu.

5. Read and acknowledge the warning by selecting I understand there may be downtime during version upgrades.

6. Click Save Changes.

gcloud

Update the cluster's release channel to a value of None:

gcloud container clusters update CLUSTER_NAME \
  --release-channel None

API

Specify "releaseChannel": { "channel": UNSPECIFIED} when you create or update a cluster.

What's next

• About release channels