Kubernetes API Versions Explained Simply: Alpha, Beta, Stable, Preferred, and Storage Versions

Bobby W

5 min read

·

Sep 29, 2026

--

Listen

Share

Press enter or click to view image in full size

If you have written a Kubernetes manifest, you have already used an API version:

apiVersion: apps/v1
kind: Deployment

But what does apps/v1 mean? What happens when an API version is deprecated? And what are preferred version and storage version?

Here is a beginner-friendly explanation.

First: group, version, and kind

Consider this manifest:

apiVersion: apps/v1
kind: Deployment

It tells Kubernetes three useful things:

• apps is the API group.
• v1 is the API version within that group.
• Deployment is the kind of object.

The core API group is slightly different. It does not include a group name:

apiVersion: v1
kind: Pod

Resources in the core group include Pods, Services, ConfigMaps, and Secrets.

The API version lifecycle

Kubernetes API versions normally move through three stability levels:

Press enter or click to view image in full size

Alpha

Alpha APIs are for testing new ideas. Built-in alpha APIs are normally disabled by default. They can contain bugs, change incompatibly, or be removed without advance notice.

Avoid them for important production workloads unless you fully understand and accept the risk.

Beta

Beta APIs are more mature, but they are not permanent interfaces. You may need to update your manifests, controllers, Helm charts, or automation when the API moves to another beta version or becomes stable.

Modern built-in beta APIs are also generally disabled by default unless explicitly enabled.

Stable, also called GA

A stable API uses a version such as v1, without alpha or beta. Kubernetes gives stable APIs its strongest compatibility commitment. For normal production use, choose the stable version when one is available.

The simple lifecycle looks like this:

v1alpha1     → v1beta1  → v1
experimental   tested     stable

However, graduation is not automatic. An alpha API can change or disappear, and version numbers may advance more than once before reaching stable.

Deprecated does not mean removed

These words have different meanings:

• Deprecated: the API still works, but you should migrate away from it.
• Removed: the API server no longer serves that version, so requests using it fail.

During a deprecation period, Kubernetes may serve both the old and replacement versions. This gives you time to update manifests and software.

For example, an object originally created through v1beta1 can usually be read through v1 while both versions are served. The object is not duplicated; the API server converts its representation.

Before upgrading a cluster, check the release notes and the Kubernetes Deprecated API Migration Guide. An old manifest can fail after an upgrade even when the existing object is still present in the cluster.

What is the preferred version?

An API group can serve more than one version at the same time. The preferred version is the version that the API server recommends to clients through API discovery.

For example, a group could serve both:

example.io/v1beta1
example.io/v1

but advertise example.io/v1 as its preferred version.

Tools such as kubectl use discovery information to understand the resources and versions supported by the cluster. You can list the served API versions with:

kubectl api-versions

You can see resources and the API versions selected by discovery with:

kubectl api-resources -o wide

For a named API group, you can inspect its preferred version directly. For example:

kubectl get --raw /apis/apps | jq '.preferredVersion'

Typical output is:

{
  "groupVersion": "apps/v1",
  "version": "v1"
}

The preferred version is a recommendation from the server. Your YAML still explicitly chooses a version through apiVersion.

What is the storage version?

The storage version is the representation Kubernetes uses when writing an object to its backing storage, commonly etcd.

Imagine that the API server serves both v1beta1 and v1:

Your YAML: v1beta1
       ↓
API server converts the object
       ↓
Stored representation: v1

When you read the object through another served version, the API server converts it again before returning it.

This means:

• The version in your YAML is the version you send to the API server.
• The preferred version is the version the server recommends through discovery.
• The storage version is the representation used at rest.

The preferred and storage versions are often the same, but they are separate concepts and should not be assumed to match.

Most application developers do not need to manage storage versions directly. They matter more to cluster administrators and people maintaining CustomResourceDefinitions.

Storage versions and CRDs

A CRD can serve multiple versions, but exactly one must be marked as its storage version:

spec:
  versions:
    - name: v1beta1
      served: true
      storage: false
    - name: v1
      served: true
      storage: true

Here, clients may use either version, but new and updated objects are stored using the v1 schema.

You can inspect a CRD with:

kubectl get crd <crd-name> \
  -o jsonpath='{range .spec.versions[*]}{.name}{"\tserved="}{.served}{"\tstorage="}{.storage}{"\n"}{end}'

Changing a CRD’s storage version does not immediately rewrite every old object. Reads can be converted dynamically, while a new write stores the object using the current storage version. Administrators may need a storage-version migration before removing an old version.

Do not confuse apiVersion with resourceVersion

Beginners often mix up these fields:

apiVersion: apps/v1
metadata:
  resourceVersion: "123456"

• apiVersion selects an API schema and endpoint.
• resourceVersion identifies a particular state of an object for concurrency and watch operations.

resourceVersion is not an alpha, beta, or stable API version. You normally let Kubernetes manage it.

A practical beginner checklist

Before applying a manifest or upgrading a cluster:

1. List what your cluster currently serves: kubectl api-versions
2. Find the API version for a resource: kubectl api-resources -o wide
3. Prefer stable versions such as apps/v1 when available.
4. Treat deprecation warnings as work to schedule, not messages to ignore.
5. Check Kubernetes release notes and the deprecation guide before upgrading.
6. Remember that CRDs have their own versions and upgrade procedures.

The most useful mental model is simple: clients choose a served version, the server recommends a preferred version, and Kubernetes writes an internal storage version. The API server handles conversion between them.

If you want more practical commands for diagnosing Kubernetes problems, download my free Kubernetes Troubleshooting Quick-Reference Kit:

Get the free Kubernetes troubleshooting kit

References

• Kubernetes API Overview
• The Kubernetes API
• Kubernetes Deprecation Policy
• Storage Versions
• Deprecated API Migration Guide