Introduction

Kubernetes periodically deprecates and removes older API versions (e.g., extensions/v1beta1, apps/v1beta1). Helm's lint command checks for these deprecated API versions and reports them as errors. Charts using deprecated APIs fail to deploy on newer Kubernetes versions that have removed the deprecated endpoints entirely.

Symptoms

  • helm lint reports deprecated API version warnings or errors
  • Chart installs on old Kubernetes but fails on upgraded cluster
  • Error message: resource mapping not found for kind Deployment in extensions/v1beta1
  • Kubernetes 1.16+ rejects apps/v1beta1 and extensions/v1beta1 Deployments
  • Error message: no matches for kind "Deployment" in version "extensions/v1beta1"

Common Causes

  • Chart created for Kubernetes 1.15 or earlier using deprecated API versions
  • Chart templates not updated after Kubernetes cluster upgrade
  • Sub-chart dependency still using deprecated API versions
  • Conditional template logic not handling API version differences across Kubernetes versions
  • Helm chart copied from an outdated tutorial or template

Step-by-Step Fix

  1. 1.Run helm lint to identify deprecated API versions: Find all deprecated resources.
  2. 2.```bash
  3. 3.helm lint ./chart
  4. 4.# Output: [WARNING] Deprecated API version: extensions/v1beta1
  5. 5.`
  6. 6.Update deprecated API versions in chart templates: Migrate to current API versions.
  7. 7.```yaml
  8. 8.# BEFORE: deprecated
  9. 9.apiVersion: extensions/v1beta1
  10. 10.kind: Deployment

# AFTER: current apiVersion: apps/v1 kind: Deployment spec: selector: matchLabels: app: my-app template: metadata: labels: app: my-app ```

  1. 1.Update other deprecated resource types: Migrate all deprecated APIs.
  2. 2.```yaml
  3. 3.# DaemonSet
  4. 4.apiVersion: apps/v1 # was extensions/v1beta1

# StatefulSet apiVersion: apps/v1 # was apps/v1beta1

# Ingress apiVersion: networking.k8s.io/v1 # was extensions/v1beta1

# PodDisruptionBudget apiVersion: policy/v1 # was policy/v1beta1

# PodSecurityPolicy # Removed in Kubernetes 1.25 - remove entirely ```

  1. 1.Use capabilities.KubeVersion for conditional API versioning: Support multiple Kubernetes versions.
  2. 2.```yaml
  3. 3.apiVersion: {{- if semverCompare ">=1.16-0" .Capabilities.KubeVersion.GitVersion }}
  4. 4.apps/v1
  5. 5.{{- else }}
  6. 6.extensions/v1beta1
  7. 7.{{- end }}
  8. 8.`
  9. 9.Verify the chart lints cleanly and deploys: Test on the target Kubernetes version.
  10. 10.```bash
  11. 11.helm lint ./chart --strict
  12. 12.helm install my-release ./chart --dry-run --debug
  13. 13.`

Prevention

  • Run helm lint --strict in CI/CD pipelines to catch deprecated API usage
  • Use pluto or kubeval to scan charts for deprecated API versions
  • Set apiVersion in Chart.yaml to v2 for Helm 3 charts
  • Test charts against the minimum supported Kubernetes version before release
  • Document the minimum Kubernetes version required by each chart
  • Subscribe to Kubernetes deprecation announcements to plan API migrations proactively