Kubernetes 1.25 Upgrade guide

The Kubernetes 1.25 release removes some deprecated resource versions.
This guide is intended to help you safely upgrade your cluster to the latest Kubernetes version that MetaKube offers.


The deprecated admission plugin "PodSecurityPolicy" will be removed with 1.25.
Differently from other resources, the PodSecurityPolicy "beta" version has not graduated to a stable version.

This means, the resource PodSecurityPolicy is no longer served by apiserver and also any previously intsalled
PodSecurityPolicy objects no longer have any effect.

There's various possible alternatives.
See the guide to migrate to the official replacement: the PodSecurity Admission controller.

Other removals

Kubernetes commonly deprecates resource versions. Deprecated versions are "marked" for removal for a future version.

All the versions that are being removed, have respective stable "v1" versions.
All objects of the resources have already been translated and stored by Kubernetes in their "preferred" version "v1".

However, the Kubernetes API will no longer accept operations on resources with versions that were removed.
This means, that clients that use these versions, will fail with errors.
The most common clients are:

  • kubectl or helm using Kubernetes manifests
  • Kubernetes operators

Most open source software for Kubernetes have released newer versions that are no longer using deprecated versions.


My helm upgrade fails because my release is referencing old resource versions

Helm is tracking "revisions" of every "release" including manifests that were installed, in Secrets.

You can look at them like so:

# to list releases
helm -n <namespace> ls

# list revisions of a release
helm -n <namespace> history <release name>

On an upgrade, Helm generates a diff to the last revision with the "Deployed" state.

Let's say, you disable PSP in your Helm chart after the upgrade to 1.25 and run an update.
Then Helm will want to delete the PSP resources that were previously installed and issues "DELETE" requests to the API.

But because the API no longer serves this resource, the requests will fail.

To fix the issue, the Helm documentation refers to this tool: helm-mapkubeapis

To avoid the issue in the first place, remove any resources with deprecated versions and run helm upgrade before upgrading the cluster.

Am I using deprecated versions?

Kubernetes won't store objects in their deprecated versions, so listing e.g. all CronJob objects, will show only v1 resources.
To find out if you're using deprecated versions:

  • Search the manifests that you deploy for deprecated versions.
  • If you're using Helm charts, use the helm template command to print the manifests that Helm installs.
  • Check the apiserver_requested_deprecated_apis{removed_release="1.25"} metric, if you scrape it.
    It shows when you've last used which deprecated resource version that gets removed with 1.25.
  • Check README files of charts for information on what Kubernetes versions each chart version supports.
  • Before upgrading your production cluster, try your "dev" cluster first, deploy your applications and check for errors in their logs.

What do I need to change?

Some resources use a modified schema, so you might have to change some fields.
The Official Deprecation Guide has detailed information on each resource.