This page explains how feature and API deprecations that are caused by Kubernetes and other dependencies work with Google Kubernetes Engine (GKE). This page also includes tables with information about specific upstream deprecations. To learn how to view your exposure to upcoming deprecations, see Viewing deprecation insights and recommendations (Preview).
What are Kubernetes deprecations?
GKE clusters are powered by the Kubernetes open source cluster management system. The feature set of Kubernetes evolves over time, and just as new features are introduced over time, sometimes a feature might need to be removed. Or, a feature may graduate from the Beta phase to the GA phase. Kubernetes deprecation policy ensures that users have a predictable process so that they can migrate away from a deprecated feature or API before it is removed.
After its deprecation period, when a feature or API is removed, you can no longer use it starting with the corresponding GKE minor version. If a cluster was dependent on a feature or API that was deprecated, functionality could be impaired.
Deprecations caused by other upstream dependencies
Apart from Kubernetes features and APIs, GKE also provides features that are powered by other providers, such as Windows node images backed by Microsoft, and Ubuntu node images backed by Canonical. When these upstream providers deprecate or end support for a feature, GKE might have to remove the corresponding feature. The tables on this page also provide information about upcoming deprecations and removals that are caused by upstream dependencies apart from Kubernetes.
How Kubernetes deprecations work with GKE
Running applications on GKE involves shared responsibility between you and GKE.
As a user, you must assess and mitigate any exposure to deprecated features and APIs that are removed in upcoming Kubernetes minor versions. In the next sections, learn about how GKE makes this process easier by detecting usage of deprecated Kubernetes features and APIs, sharing insights about this usage, and providing recommendations about how to migrate to features and APIs compatible with upcoming minor versions.
If GKE detects that a cluster is using a feature that is removed in an upcoming minor version of Kubernetes, automatic cluster upgrades to the next minor version are paused, and GKE shares a deprecation insight and recommendation.
What happens when GKE pauses automatic upgrades?
If GKE detects usage of a deprecated feature or API, GKE pauses automatic upgrades to prevent your cluster from being upgraded into a broken state. Upgrades to the next Kubernetes minor version are paused, but GKE continues to deliver patch upgrades to the cluster on the current minor version. For example, if a cluster is on version 1.21.11-gke.1100 and has calls to deprecated APIs that are removed from version 1.22, GKE pauses the automatic upgrade to version 1.22. However, GKE does not pause the automatic upgrade to a new patch version, 1.21.11-gke.1900.
As GKE cannot guarantee that all usage is detected, GKE cannot guarantee that upgrades are always paused when a deprecated feature or API is used. To ensure that a cluster is not upgraded, you must use maintenance exclusions.
When does GKE resume automatic upgrades?
Once GKE has not detected usage of the deprecated feature or calls to deprecated APIs for 30 days, the cluster is automatically upgraded if the next minor version is the default version in the cluster's release channel. To see when the minor version becomes default in your cluster's release channel, see the Release Schedule.
When GKE upgrades a cluster, the control plane is upgraded first. The node pools are upgraded to match the control plane's new version.
If GKE continues to detect usage of the deprecated feature on the cluster, then GKE keeps the cluster on its current minor version until the version's end of life date. Once this date—which is available in the Release Schedule—is reached, the cluster is automatically upgraded to the next minor version and the cluster environment might be impaired as the removed feature is still being used. To learn more, read the Version support FAQ.
What are deprecation insights and recommendations?
If GKE detects that a cluster is using a feature that is removed in an upcoming minor version of Kubernetes, GKE shares a deprecation insight and recommendation, notifying you of your cluster's usage of a deprecated feature. This insight provides information about last detected usage, and further details depending on the type of deprecation. To learn about viewing this information, see Viewing deprecation insights and recommendations (Preview).
Assess and mitigate exposure to upcoming Kubernetes deprecations
GKE provides migration guides that instruct you how to migrate from deprecated features and APIs to those compatible with the upcoming minor version. For a list of upcoming deprecations and their migration guides, see Kubernetes deprecations information.
While GKE shares insights about clusters it has detected are exposed to a deprecation, detection of all exposures to upcoming deprecations is not guaranteed. For example, if a deprecated feature has not been used in the last 30 days, GKE does not detect any usage, and an insight and recommendation is not generated.
You must independently assess your cluster environment's exposure to any upcoming deprecations before you upgrade your cluster to the next minor version. You can exercise control over the upgrade process by choosing a release channel, using maintenance windows and exclusions, or manually upgrading your clusters if you have determined that they are not exposed to deprecations on the next minor version.
Resolving exposure to Kubernetes deprecations
You can take action by reviewing upcoming deprecations. View deprecation insights and recommendations (Preview), to assess if your cluster is exposed, and use migration guides to mitigate the exposure before the last available minor version supporting the feature reaches its end of life.
After you make changes to stop usage of deprecated APIs or features in your cluster, GKE waits until it has no longer observed use of deprecated APIs or features for 30 days, and then unblocks automatic upgrades. Automatic upgrades proceed according to the release schedule.
You can also upgrade your cluster manually if you've confirmed that the upgrade does not cause disruption to your cluster environment. You can do this by first creating a test cluster and checking whether the upgrade causes any disruption. If it does not, you can manually upgrade your cluster.
When you dismiss a recommendation, you only hide it for all users. Automatic upgrades remain paused until you migrate out of the deprecated features and GKE does not detect usage of the deprecated features for 30 consecutive days.
Kubernetes deprecations information
The following sections provide information about ongoing deprecations, including guides explaining how to migrate to features or APIs compatible with available Kubernetes minor versions. You can check these tables to see if GKE detects and reports usage with insights and recommendations.
Kubernetes feature deprecations
The following table outlines ongoing GKE feature deprecations, as well as the version in which those features are no longer supported:
|Name||Deprecated||Removed||More information||Does GKE detect and report usage?|
|Built-in authentication plugin for Kubernetes clients||GKE version 1.22||GKE version 1.25||Deprecated authentication plugin for Kubernetes clients||No|
|PodSecurityPolicy||GKE version 1.21||GKE version 1.25||PodSecurityPolicy deprecation||No|
|Docker-based node images||GKE version 1.20||GKE version 1.24||Docker node image deprecation||Yes|
|X.509 Common Name field in webhook certificates||GKE version 1.19||GKE version 1.23||Webhook certificates CN field deprecation||Yes|
Kubernetes API deprecations
The following table provides an overview of Kubernetes APIs that are deprecated and no longer served, sorted by Kubernetes version:
|Kubernetes version||More information||Does GKE detect and report usage?|
|1.25||Kubernetes 1.25 deprecated APIs||No|
|1.22||Kubernetes 1.22 deprecated APIs||Yes|
|1.16||Kubernetes 1.16 deprecated APIs||No|
Other feature deprecations
The following table provides information on deprecations and removals that are caused by other upstream providers that are not part of the Kubernetes open source project.
|Name||Deprecated||Removed||More information||Does GKE detect and report usage?|
|Windows Server Semi-Annual Channel (SAC) node images||N/A||August 9, 2022||Windows Server SAC end of servicing||No|