Estimated reading time: 6 minutes
Every object or resource you create on Kubernetes must be defined using an apiVersion. The apiVersion is a critical part of the resource’s API path and indicates the API’s stability and maturity. It follows the format: group/version. For example, apps/v1 or batch/v1beta1.
Different API versions indicate different levels of stability and support. The Kubernetes API Changes documentation provides more information about the criteria for each level.
Table of contents
Finding the right apiVersion to use in your Kubernetes Cluster
Given the many plugins and features you can enable on your Kubernetes cluster, it’s understandably difficult to remember the right apiVersion to use for the objects you create. When upgrading from one Kubernetes version to another, it is also a concern when you must confirm if your application breaks if the apiVersion graduates to a new level.
Fortunately, Kubernetes has a command that will print all the supported API resources on the cluster, along with the name, shortcode, the Kind of the resource and the respective apiVersion you need to use when creating the resource.
Run the command:
kubectl api-resourcesThis command will print all the supported API resources on the server.
For example, on a cluster running Kubernetes v1.27, the command would print the following output:
Different Levels Kubernetes apiVersion
Here’s a look at the different levels of the apiVersion and what they mean:
Alpha Level
Alpha-level features in Kubernetes are denoted by apiVersions that include alpha, such as v1alpha1. These features are committed to the main Kubernetes repository and appear in official releases but are disabled by default. Users can enable these features via flags. The primary audience for alpha features includes developers and expert users interested in providing early feedback. However, completeness is not guaranteed; some API operations, CLI commands, or UI support may be absent. Additionally, alpha APIs may not have undergone an extensive API review, which is more rigorous than standard code reviews.
The upgradability of alpha Kubernetes apiVersion features is a significant concern, as the object schema and semantics may change in later releases without any provisions for preserving existing objects in a cluster. This lack of upgradability allows developers to iterate rapidly and increment API versions more frequently than the standard release cadence. However, developers must still update the API version when making incompatible object schema or semantics changes. Due to the newness of these features and the potential lack of end-to-end testing, enabling alpha features may expose bugs that can destabilize the cluster, such as control loop bugs that rapidly create excessive objects, exhausting API storage.
The Kubernetes project does not commit to completing or maintaining alpha Kubernetes apiVersion features and may entirely remove them in future releases. Remember to use alpha features only in short-lived testing clusters, considering these factors.. Their complexity, lack of long-term support, and potential instability make them unsuitable for production environments. When experimenting with these features, users should be cautious and prepared for rapid changes and potential instability.
Beta level
Beta-level features in Kubernetes are identified by API versions that include beta, such as v2beta3. The official Kubernetes releases include these features, which are usually disabled by default. However, you can set a flag and enable them. Before version 1.24, beta APIs were automatically enabled, but this policy has changed for new beta APIs. These beta features aim to engage users in providing feedback and helping to refine the feature before it becomes stable.
Beta features are more complete than alpha features. All API operations, CLI commands, and UI are implemented, and end-to-end tests are completed. Additionally, the API would have undergone a thorough review and be considered complete, although real-world use during the beta phase may reveal unforeseen issues. While the object schema and semantics of beta features may still change in future releases, there will be a documented upgrade path. This might involve automatically converting objects to the new version or a manual upgrade process requiring downtime and manual object conversion. When manual conversion is necessary, comprehensive documentation will guide users through the process.
Beta features offer better cluster reliability than alpha features, as they come with end-to-end tests and are less likely to introduce bugs in unrelated features. However, minor bugs may still exist since the feature is relatively new. The Kubernetes project commits to completing and stabilizing beta features in a subsequent stable version, typically within three months. However, this can sometimes take longer. During the transition period, releases will support two consecutive versions to give users ample time to upgrade and migrate objects. Remember that beta features are appropriate for use in short-lived testing clusters. You can also evaluate them in production clusters for short periods to provide valuable feedback.
The Stable-Level Kubernetes apiVersion
Stable-level features in Kubernetes are denoted by apiVersions with an integer, such as v1. These features are included in official Kubernetes releases and are enabled by default, making them readily available for all users. Due to their robustness and reliability, the primary audience for stable features includes everyone using Kubernetes, from beginners to advanced users.
Stable features are required to have conformance tests approved by the SIG Architecture. These tests ensure the features function correctly and reliably within the appropriate conformance profile. This may include non-portable and optional features not part of the default profile. Because of this thorough testing and approval process, stable features are considered complete and highly reliable. Moreover, any changes to these features in subsequent software releases must be strictly compatible, ensuring users can upgrade their clusters without worrying about breaking changes.
The high level of reliability and support in the stable-level Kubernetes apiVersions makes stable features ideal for any use case. The API version for stable features will remain available for many subsequent software releases, providing long-term stability and support. This allows users to confidently use these features in production environments, knowing they have the backing of the Kubernetes community and a solid foundation of conformance tests and compatibility assurances. Stable features are recommended for all users, whether for development, testing, or production workloads, due to their proven reliability and ongoing support.
Conclusion
As we saw above, each apiVersion level in Kubernetes offers different stability, reliability, and support levels. Use Alpha versions if you’re a developer or an expert user eager to test new features and provide early feedback. However, be aware of the potential instability and lack of upgrade paths. Beta versions are suitable for users who want to evaluate features in a more reliable environment and are prepared to handle minor bugs and occasional manual upgrades. Finally, Stable versions are ideal for all users, especially for production environments, as they offer high reliability, comprehensive support, and guaranteed long-term availability. By choosing the correct API version, you can balance innovation with stability, ensuring your Kubernetes clusters run smoothly and efficiently.
