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.
Get my book Golden Guide to Kubernetes Application Development. If you’re a web application developer who wants to become a Kubernetes expert very quickly, check out the book.
apiVersion should I use?
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’ 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.
These do not contain ‘alpha’ or ‘beta’ in their name. They are safe to use.
This was the first stable release of the Kubernetes API. It contains many core objects.
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.
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 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.
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.
This API release adds functionality to validate network certificates for secure communication in your cluster. You can read more on the official docs.
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
extensions/v1beta1 is becoming deprecated—try to use the specific API group where possible, depending on your Kubernetes cluster version.
This apiVersion adds the ability to set a pod disruption budget and new rules around pod security.
This apiVersion includes extra functionality for Kubernetes role-based access control. This helps you to secure your cluster. Check out the official blog post.