Helm Upgrade Failed After v1.25 Due to PDB API

We recently started upgrading one of our oldest Kubernetes clusters. This cluster had been running reliably on v1.19 for years without issue. Now that we’re preparing to bring it up to v1.31, we decided to step through the intermediate versions. Everything was smooth—until we hit v1.25.

That’s when Helm threw an unexpected error and blocked the upgrade:

Error: UPGRADE FAILED: resource mapping not found for name: "<object-name>" namespace: "<object-namespace>" from "": no matches for kind "PodDisruptionBudget" in version "policy/v1beta1"
ensure CRDs are installed first

No application code had changed. The chart logic was untouched. Just the Kubernetes version was bumped. So what happened?

The Gotcha: Removed API in Helm Metadata¶

We had overlooked one detail: one of our internal Helm charts still referenced the PodDisruptionBudget (PDB) API version policy/v1beta1, which was removed in Kubernetes v1.25.

Even after we corrected the chart to use the updated policy/v1 API, the upgrade still failed. That’s because Helm’s release metadata was still referencing the removed API.

Helm keeps track of all resources associated with a release, and if one of them refers to an API version that no longer exists in the cluster, it refuses to proceed.

Enter: helm-mapkubeapis¶

helm-mapkubeapis is a Helm plugin built specifically to address this issue. It scans Helm release metadata for deprecated or removed Kubernetes APIs and updates them in-place to supported versions.

Installation¶

helm plugin install https://github.com/helm/helm-mapkubeapis

Be sure to install v0.4.1 or later, as earlier versions don’t fully support resource removal.

How I Fixed the Problem¶

Once the plugin was installed, I followed these two steps:

1. Dry Run¶

Check what changes would be applied:

helm mapkubeapis --dry-run <release-name> --namespace <namespace>

The plugin correctly identified the policy/v1beta1 reference in the metadata.

2. Apply the Rewrite¶

Update the release metadata in-place:

helm mapkubeapis <release-name> --namespace <namespace>

A new release revision was created with the corrected references—and the Helm upgrade succeeded.

Important: Update Your Charts Too¶

The plugin fixes Helm’s internal records, but your actual chart templates still need to be updated manually. Here’s the change we made:

# BEFORE
apiVersion: policy/v1beta1
kind: PodDisruptionBudget

# AFTER
apiVersion: policy/v1
kind: PodDisruptionBudget

Make sure all of your manifests—Deployments, CRDs, PDBs—use API versions supported by your cluster.

Key Takeaways¶

• Kubernetes v1.25 removes policy/v1beta1, not just deprecates it.
• Helm stores API references from past releases. Even if your charts are up to date, metadata can block upgrades.
• Use helm-mapkubeapis to rewrite Helm release history safely and unblock upgrades.

We’ve now added this plugin to our standard upgrade procedure to avoid similar issues in future migrations.

Have you hit similar snags upgrading across Kubernetes versions? I’d love to hear how you handled them.