Kubernetes - API
Kubernetes API serves as a foundation for declarative configuration schema for the system. Kubectl command-line tool can be used to create, update, delete, and get API object. Kubernetes API acts a communicator among different components of Kubernetes.
Adding API to Kubernetes
Adding a new API to Kubernetes will add new features to Kubernetes, which will increase the functionality of Kubernetes. However, alongside it will also increase the cost and maintainability of the system. In order to create a balance between the cost and complexity, there are a few sets defined for it.
The API which is getting added should be useful to more than 50% of the users. There is no other way to implement the functionality in Kubernetes. Exceptional circumstances are discussed in the community meeting of Kubernetes, and then API is added.
API Changes
In order to increase the capability of Kubernetes, changes are continuously introduced to the system. It is done by Kubernetes team to add the functionality to Kubernetes without removing or impacting the existing functionality of the system.
To demonstrate the general process, here is an (hypothetical) example −
A user POSTs a Pod object to /api/v7beta1/...
The JSON is unmarshalled into a v7beta1.Pod structure
Default values are applied to the v7beta1.Pod
The v7beta1.Pod is converted to an api.Pod structure
The api.Pod is validated, and any errors are returned to the user
The api.Pod is converted to a v6.Pod (because v6 is the latest stable version)
The v6.Pod is marshalled into JSON and written to etcd
Now that we have the Pod object stored, a user can GET that object in any supported API version. For example −
A user GETs the Pod from /api/v5/...
The JSON is read from etcd and unmarshalled into a v6.Pod structure
Default values are applied to the v6.Pod
The v6.Pod is converted to an api.Pod structure
The api.Pod is converted to a v5.Pod structure
The v5.Pod is marshalled into JSON and sent to the user
The implication of this process is that API changes must be done carefully and backward compatibly.
API Versioning
To make it easier to support multiple structures, Kubernetes supports multiple API versions each at different API path such as /api/v1 or /apsi/extensions/v1beta1
Versioning standards at Kubernetes are defined in multiple standards.
Alpha Level
This version contains alpha (e.g. v1alpha1)
This version may be buggy; the enabled version may have bugs
Support for bugs can be dropped at any point of time.
Recommended to be used in short term testing only as the support may not be present all the time.
Beta Level
The version name contains beta (e.g. v2beta3)
The code is fully tested and the enabled version is supposed to be stable.
The support of the feature will not be dropped; there may be some small changes.
Recommended for only non-business-critical uses because of the potential for incompatible changes in subsequent releases.
Stable Level
