Migrate Off Deprecated APIs

Why this matters

Every Kubernetes minor release retires API versions, and clusters eventually refuse the old ones outright. Manifests copied from old guides carry versions that no longer serve, and the failure arrives as a flat rejection at the worst moment: during an upgrade, a restore, or an exam task with a clock running.

Concepts

Deprecation warns, removal refuses: the API server prints warnings for deprecated versions while still serving them, then later versions drop them entirely. kubectl apply --dry-run=server surfaces warnings against your actual cluster. Release notes list removals per minor version; the exam expects you to know the famous ones (batch v1 for Jobs and CronJobs, autoscaling v2, policy v1 for PodDisruptionBudgets) and to convert the rest by reading schema.

Conversion is mechanical: change apiVersion, adjust renamed or restructured fields per kubectl explain on the new version, dry-run, diff, apply. Storage migration (the cluster rewriting stored objects) happens separately during upgrades and is the administrators' concern; your manifests just need to speak a served version.

Worked example

An old CronJob speaking a retired batch version, converted calmly:

# find it
grep -rn "batch/v1beta1" manifests/     # the suspect
# read the replacement shape from the cluster itself
kubectl explain cronjob.spec --api-version=batch/v1 | head -30
# convert: apiVersion batch/v1, jobTemplate unchanged in shape,
# schedule untouched, then validate the new file
kubectl apply --dry-run=server -f cronjob.yaml
kubectl diff -f cronjob.yaml || true
kubectl apply -f cronjob.yaml
kubectl get cronjob nightly-report -o yaml | grep apiVersion

The cluster's own explain output is the migration guide: fields that exist in the new version are legal, fields that do not are the rewrite list.

Exam notes

Serving warnings appear on stderr and in audit logs, not as apply failures: silence is not approval. Different clusters serve different versions, so the same manifest migrates on one cluster and breaks on another: always validate against the target. And CRDs version independently of built-ins: check the operator's docs, not the Kubernetes release notes, for those.