If you work with Kubernetes you have most likely worked with deployment manifests. These files define the objects (kind:) you want to create and the version (apiVersion:) of the API to interact with. Here is a sample:
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1beta1
metadata:
name: flannel
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: flannel
subjects:
- kind: ServiceAccount
name: flannel
namespace: kube-system
Kubernetes is a work in progress so the APIs you interact with are versioned to reflect their current sate. The official API documentation lists three possible states:
What is super interesting is that Kubernetes supports multiple API versions, and these versions can be made more granular by versioning at specific API paths:
To make it easier to eliminate fields or restructure resource representations, Kubernetes supports multiple API versions, each at a different API path, such as /api/v1 or /apis/extensions/v1beta1.
Another interesting factoid (at least it is to me) is that versions are applied at the API level:
We chose to version at the API level rather than at the resource or field level to ensure that the API presents a clear, consistent view of system resources and behavior, and to enable controlling access to end-of-lifed and/or experimental APIs.
This is super cool but you often want to know WHICH versions are supported by a given Kubernetes release. Luckily for us the kubectl utility has an “api-versions” command to list the versions supported by a given release:
$ kubectl api-versions
apiextensions.k8s.io/v1beta1
apiregistration.k8s.io/v1beta1
apps/v1beta1
apps/v1beta2
authentication.k8s.io/v1
authentication.k8s.io/v1beta1
authorization.k8s.io/v1
authorization.k8s.io/v1beta1
autoscaling/v1
autoscaling/v2beta1
batch/v1
batch/v1beta1
certificates.k8s.io/v1beta1
extensions/v1beta1
networking.k8s.io/v1
policy/v1beta1
rbac.authorization.k8s.io/v1
rbac.authorization.k8s.io/v1beta1
storage.k8s.io/v1
storage.k8s.io/v1beta1
v1
As I read more about the API I’m blown away by how well thought out it is. Viva la K8S!