5.4 Kubernetes API Version Model

Kubernetes API Version Model is the discipline governing how individual API versions within a group are labeled according to their maturity, how multiple versions of the same underlying resource type coexist and are converted between one another, and how the project's deprecation policy governs the pace at which older versions can eventually be removed from the API surface.

Maturity Level Naming Conventions

Alpha Versions

Alpha versions, denoted with a suffix such as v1alpha1, represent experimental functionality that may contain bugs, may be disabled by default, and carries no compatibility guarantee whatsoever; the API shape, behavior, or even the resource's existence can change or be removed entirely between releases without a deprecation cycle.

Beta Versions

Beta versions, denoted with a suffix such as v1beta1, indicate functionality that is well-tested and enabled by default, with the overall feature considered reasonably stable, though the detailed API shape may still undergo minor changes before reaching general availability, and beta versions still require an eventual deprecation and removal path once superseded.

Stable Versions

Stable versions, denoted simply as v1, v2, and so on without an alpha or beta suffix, carry Kubernetes' strongest compatibility guarantee: once published, a stable version's API will remain supported for a long, clearly communicated duration, and existing fields will not be removed or have their meaning changed in incompatible ways.

Multiple Versions of a Single Kind

Coexistence During Migration

It is common for a resource kind to be simultaneously available at more than one version, for example both v1beta1 and v1, during a transition period, giving existing automation and manifests time to migrate to the newer version before the older one is eventually removed.

Conversion Between Versions

The API server is responsible for converting objects between the different versions of the same kind that it serves, using conversion functions, so that a client requesting v1beta1 and a client requesting v1 of the same underlying object both receive a correctly shaped representation, regardless of which version the object was originally created or stored as.

The Storage Version

Among the versions a resource is available at, exactly one is designated the storage version, the actual shape persisted in etcd; all other served versions are produced by converting from this canonical stored representation at request time, which is why storage version changes require careful migration handling.

The Deprecation Policy

Guaranteed Support Windows

Kubernetes' formal API deprecation policy specifies minimum support durations for each maturity level once a version is deprecated: generally available (stable) APIs must be supported for a defined minimum number of releases or months after deprecation is announced, while beta and alpha APIs have progressively shorter guaranteed windows.

Deprecation Signaling

When a version is deprecated, the API server surfaces warnings through response headers and audit logging, and release notes explicitly document the deprecation along with the recommended replacement version, giving cluster operators and application authors clear, actionable migration guidance.

Removal Requires a Deprecation Cycle

A stable API version cannot simply be deleted; it must first go through a formal deprecation announcement and honor the minimum support window before removal, a policy specifically designed to prevent the kind of abrupt breaking changes that would undermine trust in the platform's compatibility guarantees.

Version Negotiation in Practice

Client-Specified Version Requests

Clients specify the version they want to interact with directly in the request path or in the apiVersion field of a submitted manifest, and the API server serves or accepts that specific version, performing any necessary conversion transparently behind the scenes.

Preferred Version Defaults

When tooling does not pin an explicit version, it typically consults the API discovery document's declared preferred version for a given group, which the API server designates, generally favoring the most mature available version to steer users toward stable, well-supported APIs by default.

Version Skew Considerations

Kubelet and API Server Compatibility

The API version model interacts with Kubernetes' broader version skew policy, which defines how far apart in release version different cluster components, such as the kubelet and the API server, are permitted to be, ensuring that API versions understood by older components remain compatible with what a slightly newer control plane serves.

Client Library Pinning

Generated client libraries are typically built against a specific set of API versions at a point in time, meaning upgrading a cluster's available API versions does not automatically require every client to be rebuilt, so long as the older versions those clients depend on remain within their supported deprecation window.