Get visibility into cluster upgrades

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.
  • Auto-upgrade history: GKE provides a snapshot into recent automatic control plane upgrades and automatic node upgrades for your cluster. For recent automatic control plane and node upgrades, you can see the initial version, the target version, and whether the upgrade succeeded, failed, or was canceled.
  • 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.

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 upgrades information at the cluster level

Console

  1. In the Google Cloud console, go to the Kubernetes Clusters page.

    Go to Kubernetes Clusters

  2. Select the name of your cluster to view its Cluster Details page.

  3. On the Cluster Details page, see the Cluster upgrades section.

gcloud

Run the following command:

gcloud beta container clusters get-upgrade-info CLUSTER_NAME

Replace CLUSTER_NAME with the name of the cluster.

Get upgrades information for Standard cluster node pools

You can use the gcloud CLI to 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.

Run the following command:

gcloud beta container node-pools get-upgrade-info POOL_NAME
    --cluster CLUSTER_NAME

Replace POOL_NAME with the name of the node pool.

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:

  • AUTO_UPGRADE_PAUSED_REASON_UNSPECIFIED: An unspecified reason.
  • 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.

What's next