2.4 Kubernetes Releases, API Versioning & Deprecation Policy

2.4 Kubernetes Releases, API Versioning & Deprecation Policy

Quick Answer: Kubernetes publishes about three minor releases per year, each supported for roughly 14 months of patch releases. Every API object carries an apiVersion whose suffix encodes maturity: alpha (experimental, off by default, may vanish without notice), beta (on by default, schema may still change), and stable/GA (v1, backward compatible). The deprecation policy guarantees a stable API element stays available for at least 12 months or 3 minor releases after it is deprecated, whichever is longer.

KCNA is a conceptual exam, but it is written against a moving platform. Almost every Kubernetes question you will meet in the wild — "why did my manifest stop working after the upgrade?", "is this field safe to depend on?" — comes down to release cadence and API maturity. This section gives you the vocabulary.

---

1. How Kubernetes Versions Are Numbered

Kubernetes follows semantic versioning in the form MAJOR.MINOR.PATCH:

The project ships minor releases on a published schedule managed by SIG Release, and each release has a named release team, an enhancements freeze, a code freeze, and a formal release-notes document. Because minor releases arrive roughly every four months, a cluster that is two years behind is already outside the supported window.

Support Window

Each minor release receives approximately 12 months of standard patch support plus an additional 2-month maintenance window, for a practical support life of about 14 months. Managed Kubernetes services (EKS, GKE, AKS) build their own, sometimes longer, support commitments on top of this upstream schedule. The operational consequence is simple and heavily tested: you cannot skip upgrades indefinitely. Falling more than three minor versions behind means you can no longer take a supported path forward.

---

2. Reading an apiVersion String

Every object manifest begins with an apiVersion. That single line tells you both where the resource lives in the API and how much you can trust it.

apiVersion: apps/v1              # named group "apps", stable version v1
apiVersion: v1                   # core group (no group name), stable
apiVersion: batch/v1             # named group "batch", stable
apiVersion: networking.k8s.io/v1 # named group, stable
apiVersion: flowcontrol.apiserver.k8s.io/v1beta3  # beta — may change

The Three Maturity Levels

Exam trap: "Beta means production ready." It does not. Beta means enabled by default, not frozen. The classic real-world example is the autoscaling API, where autoscaling/v2beta1 and autoscaling/v2beta2 both existed before autoscaling/v2 stabilised, and manifests had to be rewritten twice.

---

3. The Deprecation Policy

Kubernetes publishes a formal deprecation policy so that operators can plan migrations instead of discovering breakage during an upgrade.

• GA (v1) API versions may be marked deprecated, but must not be removed within a major version of Kubernetes. In practice a stable API you depend on today keeps being served for the whole of the 1.x line.
• Beta API versions are deprecated no more than 9 months or 3 minor releases after introduction (whichever is longer), and stop being served 9 months or 3 minor releases after deprecation (whichever is longer).
• Alpha API versions may be removed in any release, without prior deprecation notice.
• A deprecated element keeps working exactly as before during the deprecation window — deprecation is an announcement, not a behaviour change.

How Deprecations Surface

1. Release notes carry a dedicated "Deprecations and Removals" section for every minor release.
2. kubectl prints a warning when you submit an object using a deprecated API version — the API server returns the notice in a Warning HTTP header.
3. The apiserver_requested_deprecated_apis metric lets Prometheus alert on deprecated API usage before the upgrade, which is the professional way to plan a migration.

The Canonical Failure

The most-cited example is the removal of the old extensions/v1beta1 Ingress and Deployment endpoints in Kubernetes v1.22, and the removal of PodSecurityPolicy in v1.25. In both cases the objects simply stopped being accepted, so clusters upgraded without a manifest migration lost the ability to create those resources. The lesson KCNA wants: removals happen at minor releases, so an upgrade is a migration event, not a maintenance event.

---

4. Feature Gates

A feature gate is a named boolean flag passed to control plane components and the kubelet that turns an in-development feature on or off, for example --feature-gates=InPlacePodVerticalScaling=true. Feature gates are how alpha features are shipped without exposing them to everyone. As a feature graduates, its gate flips to on-by-default at beta and is eventually removed entirely once the feature is GA and unconditional.

---

5. Version Skew: What Is Allowed to Differ

Kubernetes only supports a bounded difference between component versions, which is why upgrades follow a strict order.

The practical rule: upgrade the control plane first, then the nodes, one minor version at a time. Jumping 1.28 straight to 1.31 is unsupported.