Resolving Helm Release Deletion Failures

Kubernetes cluster

Helm

Unable to uninstall a Helm release, which has become stuck in an uninstalling or other pending state. This issue often occurs after a Kubernetes cluster has been upgraded to a newer version that no longer supports the API versions used by the Helm chart.

When you attempt to delete the release, you receive an error message indicating that a deprecated or removed API resource could not be found.

For example:

Error: failed to delete release: [release-name]

uninstall.go:117: [debug] uninstall: Failed to delete release: [unable to build kubernetes objects for delete: resource mapping not found for name: "[release-name]" namespace:
"" from "": no matches for kind "[CRD-name]" in version "example.crd.io/v1alpha3"
ensure CRDs are installed first]

The recommended way to fix this is by using the mapkubeapis Helm plugin. This tool updates the metadata of a Helm release, replacing deprecated API versions with their supported equivalents, allowing Helm to successfully interact with the cluster's current API server.

Step 1: Install the mapkubeapis Plugin First, install the plugin if you don't already have it.

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

Step 2: Update the Release Metadata Next, run the plugin against your problematic release. This command will scan the release metadata for outdated APIs and update them to the current, supported versions. In this example, we'll use a release named app-metrics in the monitoring namespace

helm mapkubeapis -n monitoring app-metrics

Step 3: Uninstall the Release Once the metadata has been updated, you can proceed with the uninstallation. Helm will now be able to find and delete the resources using the correct APIs.

helm uninstall app-metrics -n monitoring

The problem lies in the Helm release's stored metadata. When a Helm chart is installed, it saves a record of the Kubernetes API versions it used.

If you later upgrade your cluster to a version that removes or changes these APIs (for instance, a transition from v1beta1 to v1), Helm's uninstallation process fails because it tries to delete resources using an API that no longer exists in the cluster. This leaves the release in an unmanageable state, preventing a clean uninstallation.