Kubernetes API Version Model

Kubernetes API Version Model is the set of conventions governing how individual versions of a resource type within an API group are named, matured, deprecated, and eventually removed, giving the platform a predictable way to evolve its API surface over time while giving API consumers clear guarantees about how much stability to expect from any given version they depend on. This model operates one level below the group model: where groups partition the API by functional domain, the version model governs how each type within a domain changes across releases.

The Maturity Levels

Alpha Versions

A version suffixed alpha (such as v1alpha1) represents an experimental stage where the API may contain bugs, may be changed or removed entirely without notice in a future release, and is typically disabled by default, reflecting that alpha features are intended for early testing and feedback rather than for production dependency.

Beta Versions

A version suffixed beta (such as v1beta1) indicates the API is more thoroughly tested and is enabled by default, with the general intent that the feature will graduate to stable, but it still carries the possibility of breaking changes, and Kubernetes' own project conventions bound how long a beta may persist without progressing.

Stable (GA) Versions

A version with no suffix (such as v1) is considered generally available and stable, meaning it will appear in released software for many subsequent major versions and any incompatible change requires a new version rather than a breaking modification to the existing one, giving long-term production workloads a version they can depend on without fear of silent behavioral changes.

Multiple Simultaneous Versions

Coexistence During Migration

A single Kind can be served under several versions simultaneously — for example, both a deprecated beta version and its stable successor — allowing clients to migrate to the newer version at their own pace within the deprecation window rather than being forced to update the instant a new version is introduced.

Storage Version and Conversion

Among the versions a Kind is served under, the API server designates one as the storage version, the form objects are actually persisted in; requests made in any other served version are converted to and from the storage version transparently, using conversion logic (either built-in for core types or a conversion webhook for CustomResourceDefinitions) that the API server invokes automatically.

Deprecation and Removal Policy

The Kubernetes Deprecation Policy

Established Kubernetes API deprecation policy specifies minimum timeframes a version must remain available after being marked deprecated before it can be removed — generally longer for GA versions than for beta, and longer for beta than for alpha — giving operators and application authors advance, predictable notice before they must migrate away from a version.

Deprecation Warnings

The API server surfaces deprecation warnings to clients making requests against a deprecated version, typically through HTTP warning headers that tools like kubectl surface directly to the user, which is intended to make deprecated usage visible during normal operation rather than only discoverable through release notes.

Version Priority in Discovery and Defaults

Preferred Version

When a group offers multiple versions, the API server's discovery information designates a preferred version, which is what a generic client uses by default when a user does not explicitly specify a version, typically the newest stable version available, ensuring clients gravitate toward the most mature option without needing hardcoded version knowledge.

Ordering Conventions

Kubernetes follows a consistent ordering convention across the ecosystem — stable versions ranked above beta, beta ranked above alpha, and within each maturity tier, higher numbers ranked above lower ones — which tooling relies on to compute the preferred version algorithmically rather than through explicit per-type configuration.

Version Model for Custom Resources

CRD Version Declarations

CustomResourceDefinitions declare their own set of served versions, a storage version among them, and optionally per-version schemas and subresource configuration, meaning the same maturity, coexistence, and conversion principles that govern built-in types are fully available to extension authors defining their own resource types.