Use release channels

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:

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.
  • If you want to enroll a cluster in the Extended channel, ensure that you've reviewed the pricing for extended support. You can enroll a cluster in the Extended channel for no additional cost if the project has enabled GKE Enterprise. Or, for GKE Standard edition clusters, pay-per-use costs apply when your cluster is enrolled in the Extended channel and your cluster's minor version enters the extended support period.

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. For the Extended channel, review Get long-term support with the Extended channel before selecting this 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.

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, stable, or, for Standard only, extended.

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.

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. To get auto-upgrade targets for a specific cluster, see Get information about a cluster's upgrades (Preview).

Enroll an existing cluster not enrolled in a release channel and with disabled node auto-upgrade

If you have an existing Standard cluster that is not enrolled in a release channel and you've disabled node auto-upgrades for one or more of the cluster's node pools, but you want to access the additional features of release channels, you can use maintenance exclusions to prevent node upgrades instead. If you change to a release channel and use maintenance exclusions, you can't prevent node auto-upgrades at a node pool level, only at a cluster level. But, you can always manually upgrade node pools.

Do the following steps to enroll an existing cluster in a release channel, while continuing to prevent automatic node upgrades:

  1. Configure a maintenance exclusion with a scope of "No upgrades". This is the only available maintenance exclusion scope for clusters not enrolled in a release channel. This prevents your cluster from potentially being immediately auto-upgraded if there is a newly eligible auto-upgrade target in the selected release channel.
  2. Enroll the existing cluster in the target release channel. With this change, GKE makes the following changes to settings on your node pools:
    1. GKE enables the node auto-upgrade setting for any node pools where the feature is disabled, but won't automatically upgrade the nodes because you've configured the maintenance exclusion in Step 1.
    2. GKE enables node auto-repair for any node pools where the feature is disabled, although you can again disable node auto-repair with the gcloud CLI if you want to keep node auto-repair disabled.
  3. Configure a maintenance exclusion with the scope of "No minor or node upgrades". This prevents all upgrades except for patch upgrades to the control plane. Now that your cluster is enrolled in a release channel, you can use this scope of maintenance exclusion, which can last to the end of support date for the minor version in your cluster's release channel.
  4. Remove the maintenance exclusion created in Step 1 now that you've added the new maintenance exclusion in the previous step.

After completing these steps, you have a cluster where GKE won't automatically upgrade the nodes until you remove the maintenance exclusion, or the minor version of the nodes reaches the end of support.

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:

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.

Change your cluster to the Extended channel

To get long-term support, keeping your cluster on that version for as long as possible, you can enroll your cluster in the Extended channel.

Ensure that you review the pricing for enrolling your cluster in the Extended channel, and the feature limitations. You can't enroll your cluster in the Extended channel if your cluster is using certain features.

Change your cluster from the Extended channel

If a cluster is enrolled in the Extended channel during the extended support period, the cluster can continue to run a minor version that is unsupported in other channels. If you want to change your cluster from the Extended channel, where the minor version is unsupported, you must take the following steps:

  1. Complete these two steps, which can be done in either order:
    1. Manually upgrade your cluster to a minor version in the standard support period available on the target release channel.
    2. Remove or modify any maintenance exclusion with an end date that exceeds the end of standard support date for that newer, supported minor version.
  2. Update the cluster's release channel.

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, extended or None.

Unsubscribe from a release channel

While you can unsubscribe your Standard cluster from a release channel, we strongly recommend that you review the comparison between clusters enrolled and not enrolled 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.

Identify clusters not enrolled in a release channel

If you have a GKE Standard cluster that isn't enrolled in a release channel, and all node pools have node auto-upgrade enabled, we recommend that you enroll the cluster in a release channel. GKE delivers this guidance with an insight and recommendation through the Recommender service. This guidance doesn't apply to Autopilot clusters, which are always enrolled in a release channel.

To find clusters not enrolled in a release channel, you can use the one of the following ways:

  • Use the Google Cloud console.
  • Use the gcloud CLI or Recommender API, by specifying the CLUSTER_RELEASE_CHANNEL_UNSPECIFIED recommender subtype.

For instructions, see how to view insights and recommendations.

To implement this recommendation, follow the instructions to enroll existing clusters. To learn more about whether you want to implement this recommendation, see About release channels. For a comparison of capabilities between a cluster enrolled or not enrolled in a release channel, review the comparison between clusters enrolled and not enrolled in a release channel.

What's next