This page explains how you can get information about upgrades for yourGoogle Kubernetes Engine (GKE) clusters. GKE automatically upgradesall clusters over time. When GKE upgrades a cluster,GKE updates the version of the Kubernetes control plane andworker nodes in separate operations.

GKE aggregates information about cluster upgrades to helpyou better understand the status of your cluster. You can get the followinginformation for a cluster:

• Auto-upgrade targets: Find which new versions GKE istargeting for your cluster, which could be patches or new minor versions,depending on your cluster's existing version and constraints. If there is noauto-upgrade target, the cluster is on the latest upgrade target already, orGKE hasn't assigned an auto-upgrade target for technical orbusiness reasons. You can also retrieve general auto-upgrade targets basedon a cluster's minor version in theGKE releasenotesVersion updates, such as the2024-R33note.
• Auto-upgrade status: GKE clusters have a status forcluster upgrades. Use this status to learn more about current upgrades, andthe constraints GKE considers when choosing when toautomatically upgrade your cluster, including factors such as maintenanceexclusions or reasons preventing upgrades. To learn more, seeClusterauto-upgrade status.

• Upgrade history: GKE provides a snapshot into recentcontrol plane upgrades and node upgrades for your cluster, including bothautomatic and manual upgrades. For recent control plane and node upgrades,you can see details such as the following:

  • Versions: the initial and target version.
  • State: whether the upgrade is still running, or if it succeeded,failed, or was canceled.
  • Time: the start and end time.
  • Start type: whether the upgrade was triggered automatically ormanually.

• End of support dates: GKE supports minor versions for upto 24 months. To learn more, see theGKE minor versionlifecycle. For end of supportdates for all current minor versions, see theEstimated schedule forreleasechannels.

• Cluster events: GKE sends cluster notifications toCloud Logging for certain events, such as when upgrades start orcomplete, when new versions are available, security bulletins, and end ofsupport dates. In addition to GKE surfacing these eventsautomatically with Cloud Logging, you can also route these notificationsto Pub/Sub. To learn more, seeClusternotifications.

Before you begin

Before you start, make sure that 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 theninitialize the gcloud CLI. If you previously installed the gcloud CLI, get the latest version by running thegcloud components update command. Earlier gcloud CLI versions might not support running the commands in this document.Note: For existing gcloud CLI installations, make sure to set thecompute/regionproperty. If you use primarily zonal clusters, set thecompute/zone instead. By setting a default location, you can avoid errors in the gcloud CLI like the following:One of [--zone, --region] must be supplied: Please specify location. You might need to specify the location in certain commands if the location of your cluster differs from the default that you set.

Get information about a cluster's upgrades

You can get information about a cluster's upgrades by using theGoogle Cloud console, or the gcloud CLI.

Get information about upgrades at the project level

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

To get aggregated information about cluster upgrades across a project, you canuse theUpgrades dashboard.

In the Google Cloud console, go to theUpgrades dashboard:

Go to Upgrades

The tabs included in this dashboard aggregate relevant information aboutupgrades such as the following:

• Statuses of recent control plane and node upgrades
• Cluster notification logs for upgrades
• Recommendations that are related to upgrades
• End of support timelines for specific minor versions
• The number of clusters in each release channel

Get upgrades information at the cluster level

gcloudcontainerclustersget-upgrade-infoCLUSTER_NAME

Get upgrades information for Standard cluster node pools

You can get visibility into individual node pools for Standardclusters. This section doesn't apply to Autopilot clusters, whereGKE manages the nodes, so there are no node pools for you tomanage.

gcloudcontainernode-poolsget-upgrade-infoPOOL_NAME--cluster=CLUSTER_NAME

Cluster auto-upgrade status

The following are the potential statuses of automatic upgrades for a cluster:

• ACTIVE: An active upgrade status.
• UNKNOWN: The upgrade status is unknown.
• MINOR_UPGRADE_PAUSED: Minor version upgrades are paused.
• UPGRADE_PAUSED: All automatic upgrades are paused.

The following are the potential reasons that GKE pauses automaticupgrades for a cluster:

• MAINTENANCE_WINDOW: A maintenance window is preventing cluster upgrades.
• MAINTENANCE_EXCLUSION_: A paused reason with this prefix indicates that amaintenance exclusion is preventing cluster upgrades. The suffix indicatesthescope of the maintenanceexclusion,such asMAINTENANCE_EXCLUSION_NO_UPGRADES.
• CLUSTER_DISRUPTION_BUDGET: After certain operations, such as clustercreation or upgrades, clusters require a cooldown period to protect thestability and availability of the cluster and its applications.
• CLUSTER_DISRUPTION_BUDGET_MINOR_UPGRADE: The cluster is outside of thecluster disruption budget for minor version upgrades.
• SYSTEM_CONFIG: Automatic upgrades are temporarily paused for technical orbusiness reasons. With this status, we recommend not performing a manualupgrade unless it's required.
• AUTO_UPGRADE_PAUSED_REASON_UNSPECIFIED: An unspecified reason.

Find information about common scenarios for cluster upgrades

Find information about common scenarios you might encounter when managingcluster upgrades.

Find when to expect your cluster's next upgrade

To learn when to expect your cluster's next upgrade so that you can plan forand qualify the upgrade to the new version, use the following resources:

• Release schedule: In theestimated schedule for releasechannels,find the estimated auto-upgrade date that corresponds with your cluster'sminor version and release channel.
• Get upgrades information at the clusterlevel: Find your cluster's auto-upgrade target.
• Cluster notifications: GKE sends a notification when anew version becomes available in a channel. After a new version becomesavailable, with the timing depending on the channel, GKEdesignates the version as an auto-upgrade target in the channel. To viewthese notifications, filter for theUpgradeAvailableEvent when youviewcluster notifications inCloud Logging.
• Releasenotes: Follow the release notes tolearn when GKE sets the new minor version as an auto-upgradetarget in the channel.

Find what is blocking your cluster's next upgrade

To learn what is blocking an upgrade so that you can unblock it, find yourcluster's auto-upgrade status. If auto-upgrades are paused, see thereason. Use one of the following methods:

• Get upgrades information at the project level(Preview). Click theUpgrades tab, where youcan see theUpgrade statusestable. Look for your cluster in the table, and see the cluster'sAuto-upgrade column.
• Get upgrades information at the cluster level to findyour cluster's auto-upgrade status.

Find when your cluster's upgrade completes

To learn when your cluster's control plane and node upgrades complete so thatyou can verify that your workloads are working as expected, use the followingresources:

• Cluster notifications: GKE sends a notification whenGKE finishes an operation to upgrade a cluster. To view thesenotifications, filter for theUpgradeInfoEvent when youview clusternotifications in Cloud Logging.
• Upgrades dashboard (Preview): Go to theUpgrade statuses table in theGoogle Cloud console. Find your cluster. If theStatus column saysUpgraded, see from theLatest update column when the upgradecompleted.
• Get upgrades information at the cluster level: Usethe gcloud CLI to find your cluster's upgrade history, whichincludes recent upgrades.

Find how long your upgrade is expected to take

To learn how long your upgrade is expected to take, you can find the duration ofpast upgrades bygetting upgrades information at the clusterlevel. See the upgrade history for recent examples.

The length of an upgrade depends on whether the control plane or nodes are beingupgraded, the upgrade strategy, Pod Disruption Budgets (PDBs), activemaintenance policies, and other factors.

Find when your cluster's minor version reaches the end of support

GKE automatically upgrades clusters that are still running minorversions past their end of support date. For more information, seeAutomaticupgrades at the end ofsupport.

To learn when your cluster's minor version reaches the end of support—forexample, to set a maintenance exclusion or understand when deprecated APIs won'tbe usable anymore—use the following resources:

• Release schedule: In theestimated schedule for releasechannels,find the end of support date that corresponds with your cluster's minorversion and release channel. For clusters that are not in the Extendedchannel, see the end of standard support date. For clusters that are in theExtended channel, see the end of extended support date.
• Cluster notifications: GKE sends a notification for whena cluster runs a minor version at or near the end of support. To view thesenotifications, filter for theUpgradeInfoEvent when youview clusternotifications inCloud Logging.
• Insights and recommendations: GKE informs you whenyour cluster is running a minor version past the end of standardsupport. For more information, seeIdentify clusters running a minorversion past the end of standardsupport.
• Get upgrades information at the clusterlevel:Find your cluster's minor version end of support date.
• Upgrades dashboard (Preview): TheUpgrades dashboard includes aVersion end of support section withspecific versions and their days remaining until end of support.

What's next

• GKE release schedule
• GKE release notes
• Cluster notifications