API Deprecations and Maintenance

Kubernetes' own deprecation policy treats API stability levels differently. A GA (v1) API version may be marked deprecated, but Kubernetes has never removed a GA API version within a major version — there is no fixed countdown the way there is for beta. A beta API version is deprecated no sooner than 9 months or 3 minor releases after it was first introduced, and stops being served no sooner than 9 months or 3 minor releases after that deprecation — whichever of the two durations is longer, in each case. An alpha API version carries no such guarantee at all and can be removed in any release with no prior deprecation notice.

This is why a manifest written years ago against a beta API can suddenly fail to apply after a routine cluster upgrade, with no warning beyond whatever the release notes said months earlier.

# No longer served as of Kubernetes v1.25
apiVersion: batch/v1beta1
kind: CronJob

# Replacement, available since v1.21
apiVersion: batch/v1
kind: CronJob

Two concrete examples worth knowing: batch/v1beta1 for CronJob was deprecated in v1.21 and stopped being served in v1.25, with batch/v1 available the whole time since v1.21; autoscaling/v2beta2 for HorizontalPodAutoscaler stopped being served in v1.26, with autoscaling/v2 available since v1.23. kubectl api-versions and kubectl api-resources query a live cluster for what it currently serves, which is the direct way to check whether a manifest's apiVersion fields still match reality before applying them.

kubectl convert used to ship as a built-in kubectl subcommand, but its deprecation was announced before v1.13 and it was removed from kubectl's core by v1.17. It now exists only as a separate kubectl-convert plugin, installed on its own (for example via krew), which rewrites a manifest file from an old apiVersion to a target one you specify.