This page explains how to prepare clusters for upgrades to GKE version 1.25. You can find API clients making calls to deprecated APIs removed in 1.25 and update those clients to use GA APIs. For more detailed information, see the Kubernetes deprecated API migration guide.
Removed APIs in 1.25
Most of the deprecated APIs in Kubernetes version 1.25 are former Beta APIs that
have since graduated from Beta (for example, v1beta1
) to GA
(for example, v1
). The GA APIs provide
longer-term compatibility guarantees
and should be used in place of the deprecated Beta APIs.
All existing objects for APIs that graduated to GA can be interacted with by using the GA APIs.
EndpointSlice
The Beta API version (discovery.k8s.io/v1beta1
) of EndpointSlice
is no
longer served as of version 1.25. This API was deprecated in version 1.21.
- Migrate manifests and API clients to use the
discovery.k8s.io/v1
API version. Refer to the following table that describes the notable changes in the GA API version:
Field Change endpoints[*].topology["kubernetes.io/hostname"]
Use endpoints[*].nodeName
.endpoints[*].topology["topology.kubernetes.io/zone"]
Use endpoints[*].zone
.endpoints[*].topology
Replaced with endpoints[*].deprecatedTopology
which is not writable in v1.
PodDisruptionBudget
The Beta API version (policy/v1beta1
) of PodDisruptionBudget
is no longer
served as of version 1.25. This API was deprecated in version 1.21.
- Migrate manifests and API clients to use the
policy/v1
API version. Refer to the following table that describes the notable changes in the GA API version:
Field Change spec.selector
An empty value ( {}
) written to apolicy/v1 PodDisruptionBudget
selects all pods in the namespace. An unset value still selects no pods.
CronJob
The Beta API version (batch/v1beta1
) of CronJob
is no longer served as of
version 1.25. This API was deprecated in version 1.21. Migrate manifests and
API clients to use the batch/v1
API version.
PodSecurityPolicy
The Beta API version (policy/v1beta1
) of PodSecurityPolicy
is no longer
served as of version 1.25. This API was deprecated in version 1.21.
For more information, see PodSecurityPolicy deprecation.
RuntimeClass
The Beta API version (node.k8s.io/v1beta1
) of RuntimeClass
is no longer
served as of version 1.25. This API was deprecated in version 1.20. Migrate
manifests and API clients to use the node.k8s.io/v1
API version.
Events
The Beta API version (events.k8s.io/v1beta1
) of Events
is no longer
served as of version 1.25. This API was deprecated in version 1.19.
- Migrate manifests and API clients to use the
v1
API version or theevents.k8s.io/v1
API version. Refer to the following table that describes the notable changes in the GA API version:
Field Change type
Limited to Normal
andWarning
.involvedObject
Renamed to regarding
.action
,reason
,reportingController
andreportingInstance
These fields are now required when creating Events. firstTimestamp
Renamed to deprecatedFirstTimestamp
and no longer permitted in new Events. UseeventTime
instead.lastTimestamp
Renamed to deprecatedLastTimestamp
and no longer permitted in new Events. Useseries.lastObservedTime
instead.count
Renamed to deprecatedCount
and no longer permitted in new Events. Useseries.count
instead.source.component
Renamed to deprecatedSource.component
and no longer permitted in new Events. UsereportingController
instead.source.host
Renamed to deprecatedSource.host
and no longer permitted in new Events. UsereportingInstance
instead.
HorizontalPodAutoscaler
The Beta API version (autoscaling/v2beta1
) of HorizontalPodAutoscaler
is
no longer served as of version 1.25. This API was deprecated in version 1.23.
Migrate manifests and API clients to use the
autoscaling/v2 HorizontalPodAutoscaler
API version.
Preparing to upgrade to version 1.25
You do not need to delete and recreate any of your API objects. All existing persisted API objects for APIs that graduated to GA can already be read and updated using the new API versions.
However, we recommend that you migrate your clients and manifests before upgrading to Kubernetes 1.25. To learn more, see Kubernetes Deprecated API Migration Guide.
You can view deprecation insights and recommendations to determine if your cluster is using Kubernetes 1.25 deprecated APIs. GKE generates deprecation insights when user agents call deprecated APIs, not from the configuration of your Kubernetes objects.
Find clusters using deprecated APIs
You can find which clusters are using deprecated APIs from deprecation insights. Deprecation insights also provide information such as which API clients are calling the deprecated APIs in your cluster.
You can also use audit logs to find which clients are making calls to deprecated APIs.
Locate API clients making write calls to deprecated APIs
For clusters with Google Cloud Observability enabled, you can use the following Admin Activity audit log query to show the use of deprecated APIs by user agents that are not Google-managed:
resource.type="k8s_cluster"
labels."k8s.io/removed-release"="DEPRECATED_API_MINOR_VERSION"
protoPayload.authenticationInfo.principalEmail:("system:serviceaccount" OR "@")
protoPayload.authenticationInfo.principalEmail!~("system:serviceaccount:kube-system:")
Replace DEPRECATED_API_MINOR_VERSION
with the minor
version where the deprecated API is removed, for example 1.22
.
Admin Activity audit logs are automatically enabled for GKE clusters. With this query, the logs show user agents making write calls to the deprecated APIs.
Locate API clients making read calls to deprecated APIs
By default, audit logs show only write calls to the deprecated APIs. To also show read calls to deprecated APIs, configure Data Access audit logs.
Follow the instructions to Configure Data Access audit logs with the Google Cloud console. In the Google Cloud console,
select the Kubernetes Engine API. In the Log Types tab in the information panel,
select Admin Read
and Data Read
.
With these logs enabled, you can now use the original query to see both read calls and write calls to the deprecated APIs.
Upgrading third-party components
Deprecation insights might display results for third-party agents that make calls to deprecated APIs in your cluster.
To resolve third-party agents calling deprecated APIs, we recommend the following best practices:
- Check with your third-party software provider for an updated version.
- Upgrade the third-party software to the latest version. If you cannot upgrade the software, you should test whether upgrading GKE to the version with the removed deprecated APIs would break your service.
We recommend that you perform this upgrade and the GKE version upgrade on a staging cluster to monitor for disruptions before you upgrade your production clusters.
Update clusters impacted by deprecations
To upgrade clusters impacted by deprecations, perform the following steps:
- Check which user agents use the deprecated APIs in the logs.
- Update the user agents that use the deprecated APIs to use supported API versions.
- Update any third-party software that calls deprecated APIs to the latest versions.
- Upgrade a test cluster and test your application in a testing environment before upgrading your production cluster to reduce the risk of disruptions when deprecated APIs are no longer available.
- If you can't update an affected user agent, upgrade a separate test cluster to check whether the upgrade causes disruptions. If the upgrade doesn't cause disruptions, you can upgrade your cluster manually.
- After you update all of the user agents, GKE waits until it has no longer observed use of deprecated APIs for 30 days, and then unblocks automatic upgrades. Automatic upgrades proceed according to the release schedule.
Resources
More information is available in the OSS Kubernetes documentation:
- Kubernetes Blog: Kubernetes Removals and Major Changes In 1.25
- Kubernetes 1.25 release notes
- Kubernetes Deprecated API Migration Guide