API Deprecations — Staying Current Across Upgrades

Detect deprecated Kubernetes APIs in manifests and Helm charts, understand the deprecation policy, and migrate before upgrades break things.

intermediate30 minRead → Lab → Quiz → Practice

🧠 Brain Warm-Up

🧠 Brain Warm-Up: You upgrade your cluster from 1.28 to 1.32. Half your kubectl apply commands start failing with "no kind is registered for the version." What happened, and how would you have caught this before the upgrade? Think before reading.

Kubernetes Deprecation Policy

Kubernetes evolves quickly. Old API versions are deprecated and eventually removed. The policy guarantees a window:

API maturity	Deprecation window	Notes
GA (v1)	≥ 12 months and ≥ 3 releases	Most stable; long window
Beta (v1beta1, v2beta1)	≥ 9 months and ≥ 3 releases	Reasonably stable
Alpha (v1alpha1)	No guarantee — can be removed next release	Never use in production

A deprecated API still works during the window. After removal, requests using that apiVersion get a 404 or "no kind registered" error.

Real Deprecation Examples

Old apiVersion	Removed in	New apiVersion
`extensions/v1beta1` Ingress	1.22	`networking.k8s.io/v1`
`apps/v1beta1` Deployment	1.16	`apps/v1`
`networking.k8s.io/v1beta1` Ingress	1.22	`networking.k8s.io/v1`
`policy/v1beta1` PodDisruptionBudget	1.25	`policy/v1`
`batch/v1beta1` CronJob	1.25	`batch/v1`

Detecting Deprecated APIs

1. kubectl warnings (built-in)

kubectl prints deprecation warnings to stderr automatically:

$ kubectl apply -f old-ingress.yaml
Warning: networking.k8s.io/v1beta1 Ingress is deprecated in v1.19+, unavailable in v1.22+;
         use networking.k8s.io/v1 Ingress
ingress.networking.k8s.io/my-ingress created

2. kubectl api-versions

List all API groups and versions currently available in the cluster:

kubectl api-versions
# apps/v1
# batch/v1
# networking.k8s.io/v1
# ...

If an apiVersion from your manifest is NOT in this list, it has been removed.

3. Pluto — automated scanning

Pluto scans directories of manifests or Helm chart outputs for deprecated and removed APIs:

# Install
brew install FairwindsOps/tap/pluto     # macOS
# or download from github.com/FairwindsOps/pluto/releases

# Scan a directory
pluto detect-files -d ./manifests

# Scan a Helm release
helm template my-release ./my-chart | pluto detect --stdin

Output:

NAME         KIND      VERSION                         REPLACEMENT              REMOVED   DEPRECATED
my-ingress   Ingress   networking.k8s.io/v1beta1       networking.k8s.io/v1     true      true

4. kubectl convert (plugin)

kubectl convert migrates manifests between API versions:

# Install via krew
kubectl krew install convert

# Convert a single file
kubectl convert -f old-ingress.yaml --output-version networking.k8s.io/v1

# Convert all files in a directory
kubectl convert -f ./manifests/ --output-version networking.k8s.io/v1 -o yaml

Pre-Upgrade Checklist

Before upgrading your cluster:

Check the release notes for the target version — look for "Removed APIs" section
Run Pluto against all manifests and Helm releases
Fix deprecated apiVersions in manifests
Test with --dry-run=server against a cluster running the new version

←

Service Mesh with Istio

KCNA: Kubernetes & Cloud Native Associate

→