Get visibility into cluster upgrades

Stay organized with collections Save and categorize content based on your preferences.

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

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

• Auto-upgrade targets: Find which new versions GKE is targeting for your cluster, which could be patches or new minor versions, depending on your cluster's existing version and constraints. If there is no auto-upgrade target, the cluster is on the latest upgrade target already, or GKE hasn't assigned an auto-upgrade target for technical or business reasons. You can also retrieve general auto-upgrade targets based on a cluster's minor version in the GKE release notes Version updates, such as the 2024-R33 note.
• Auto-upgrade status: GKE clusters have a status for cluster upgrades. Use this status to learn more about current upgrades, and the constraints GKE considers when choosing when to automatically upgrade your cluster, including factors such as maintenance exclusions or reasons preventing upgrades. To learn more, see Cluster auto-upgrade status.

• Upgrade history: GKE provides a snapshot into recent control plane upgrades and node upgrades for your cluster, including both automatic 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 or manually.

• End of support dates: GKE supports minor versions for up to 24 months. To learn more, see the GKE minor version lifecycle. For end of support dates for all current minor versions, see the Estimated schedule for release channels.

• Cluster events: GKE sends cluster notifications to Cloud Logging for certain events, such as when upgrades start or complete, when new versions are available, security bulletins, and end of support dates. In addition to GKE surfacing these events automatically with Cloud Logging, you can also route these notifications to Pub/Sub. To learn more, see Cluster notifications.

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.

Get information about a cluster's upgrades

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

Get information about upgrades at the project level

To get aggregated information about cluster upgrades across a project, you can use the Upgrades dashboard.

In the Google Cloud console, go to the Upgrades dashboard:

Go to Upgrades

The tabs included in this dashboard aggregate relevant information about upgrades 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

gcloud beta container clusters get-upgrade-info CLUSTER_NAME

Get upgrades information for Standard cluster node pools

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

gcloud beta container node-pools get-upgrade-info POOL_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 automatic upgrades for a cluster:

• MAINTENANCE_WINDOW: A maintenance window is preventing cluster upgrades.
• MAINTENANCE_EXCLUSION_: A paused reason with this prefix indicates that a maintenance exclusion is preventing cluster upgrades. The suffix indicates the scope of the maintenance exclusion, such as MAINTENANCE_EXCLUSION_NO_UPGRADES.
• CLUSTER_DISRUPTION_BUDGET: After certain operations, such as cluster creation or upgrades, clusters require a cooldown period to protect the stability and availability of the cluster and its applications.
• CLUSTER_DISRUPTION_BUDGET_MINOR_UPGRADE: The cluster is outside of the cluster disruption budget for minor version upgrades.
• SYSTEM_CONFIG: Automatic upgrades are temporarily paused for technical or business reasons. With this status, we recommend not performing a manual upgrade 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 managing cluster 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 for and qualify the upgrade to the new version, use the following resources:

• Release schedule: In the estimated schedule for release channels, find the estimated auto-upgrade date that corresponds with your cluster's minor version and release channel.
• Get upgrades information at the cluster level: Find your cluster's auto-upgrade target.
• Cluster notifications: GKE sends a notification when a new version becomes available in a channel. After a new version becomes available, with the timing depending on the channel, GKE designates the version as an auto-upgrade target in the channel. To view these notifications, filter for the UpgradeAvailableEvent when you view cluster notifications in Cloud Logging.
• Release notes: Follow the release notes to learn when GKE sets the new minor version as an auto-upgrade target 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 your cluster's auto-upgrade status. If auto-upgrades are paused, see the reason. Use one of the following methods:

• Get upgrades information at the project level (Preview). Click the Upgrades tab, where you can see the Upgrade statuses table. Look for your cluster in the table, and see the cluster's Auto-upgrade column.
• Get upgrades information at the cluster level to find your 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 that you can verify that your workloads are working as expected, use the following resources:

• Cluster notifications: GKE sends a notification when GKE finishes an operation to upgrade a cluster. To view these notifications, filter for the UpgradeInfoEvent when you view cluster notifications in Cloud Logging.
• Upgrades dashboard (Preview): Go to the Upgrade statuses table in the Google Cloud console. Find your cluster. If the Status column says Upgraded, see from the Latest update column when the upgrade completed.
• Get upgrades information at the cluster level: Use the gcloud CLI to find your cluster's upgrade history, which includes 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 of past upgrades by getting upgrades information at the cluster level. See the upgrade history for recent examples.

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

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

GKE automatically upgrades clusters that are still running minor versions past their end of support date. For more information, see Automatic upgrades at the end of support.

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

• Release schedule: In the estimated schedule for release channels, find the end of support date that corresponds with your cluster's minor version and release channel. For clusters that are not in the Extended channel, see the end of standard support date. For clusters that are in the Extended channel, see the end of extended support date.
• Cluster notifications: GKE sends a notification for when a cluster runs a minor version at or near the end of support. To view these notifications, filter for the UpgradeInfoEvent when you view cluster notifications in Cloud Logging.
• Insights and recommendations: GKE informs you when your cluster is running a minor version past the end of standard support. For more information, see Identify clusters running a minor version past the end of standard support.
• Get upgrades information at the cluster level: Find your cluster's minor version end of support date.
• Upgrades dashboard (Preview): The Upgrades dashboard includes a Version end of support section with specific versions and their days remaining until end of support.

What's next

• GKE release schedule
• GKE release notes
• Cluster notifications