Which Kubernetes apiVersion Should I Use?

An object definition in Kubernetes requires an apiVersion field. When Kubernetes has a release that updates what is available for you to use—changes something in its API—a new apiVersion is created.

However, the official Kubernetes documentation provides little guidance on apiVersion. This guide gives you a cheat sheet on which version to use, explains each version, and gives you the timeline of releases.

Last updated 4 June, 2018. Contact me to report inaccuracies.


This is an excerpt from my book, Golden Guide to Certified Kubernetes Application Development. If you’re a web application developer who wants to become a Kubernetes expert very quickly, check out the book.

Which apiVersion should I use?

Kind apiVersion
CertificateSigningRequestcertificates.k8s.io/v1beta1
ClusterRoleBindingrbac.authorization.k8s.io/v1
ClusterRolerbac.authorization.k8s.io/v1
ComponentStatusv1
ConfigMapv1
ControllerRevisionapps/v1
CronJobbatch/v1beta1
DaemonSetextensions/v1beta1
Deploymentextensions/v1beta1
Endpointsv1
Eventv1
HorizontalPodAutoscalerautoscaling/v1
Ingressextensions/v1beta1
Jobbatch/v1
LimitRangev1
Namespacev1
NetworkPolicyextensions/v1beta1
Nodev1
PersistentVolumeClaimv1
PersistentVolumev1
PodDisruptionBudgetpolicy/v1beta1
Podv1
PodSecurityPolicyextensions/v1beta1
PodTemplatev1
ReplicaSetextensions/v1beta1
ReplicationControllerv1
ResourceQuotav1
RoleBindingrbac.authorization.k8s.io/v1
Rolerbac.authorization.k8s.io/v1
Secretv1
ServiceAccountv1
Servicev1
StatefulSetapps/v1

What does each apiVersion mean?

alpha
API versions with ‘alpha’ in their name are early candidates for new functionality coming into Kubernetes. These may contain bugs and are not guaranteed to work in the future.

beta
‘beta’ in the API version name means that testing has progressed past alpha level, and that the feature will eventually be included in Kubernetes. Although the way it works might change, and the way objects are defined may change completely, the feature itself is highly likely to make it into Kubernetes in some form.

stable
These do not contain ‘alpha’ or ‘beta’ in their name. They are safe to use.




v1
This was the first stable release of the Kubernetes API. It contains many core objects.

apps/v1
apps is the most common API group in Kubernetes, with many core objects being drawn from it and v1. It includes functionality related to running applications on Kubernetes, like Deployments, RollingUpdates, and ReplicaSets.

autoscaling/v1
This API version allows pods to be autoscaled based on different resource usage metrics. This stable version includes support for only CPU scaling, but future alpha and beta versions will allow you to scale based on memory usage and custom metrics.

batch/v1
The batch API group contains objects related to batch processing and job-like tasks (rather than application-like tasks like running a webserver indefinitely). This apiVersion is the first stable release of these API objects.

batch/v1beta1
A beta release of new functionality for batch objects in Kubernetes, notably including CronJobs that let you run Jobs at a specific time or periodicity.

certificates.k8s.io/v1beta1
This API release adds functionality to validate network certificates for secure communication in your cluster. You can read more on the official docs.

extensions/v1beta1
This version of the API includes many new, commonly used features of Kubernetes. Deployments, DaemonSets, ReplicaSets, and Ingresses all received significant changes in this release.

Note that in Kubernetes 1.6, some of these objects were relocated from extensions to specific API groups (e.g. apps). When these objects move out of beta, expect them to be in a specific API group like apps/v1. Using extensions/v1beta1 is becoming deprecated—try to use the specific API group where possible, depending on your Kubernetes cluster version.

policy/v1beta1
This apiVersion adds the ability to set a pod disruption budget and new rules around pod security.

rbac.authorization.k8s.io/v1
This apiVersion includes extra functionality for Kubernetes role-based access control. This helps you to secure your cluster. Check out the official blog post.