kubernetes, api

Kubernetes API Resources: Which Group and Version to Use?

Last update:

Kubernetes uses declarative API which makes the system more robust. But, this means that we create an object using CLI or REST to represent what we want the system to do. For representation, we need to define things like API resource name, group, and version. But users get confused. The main reason for the confusion is that we as humans are not good at remembering things like this. In one deployment definition you could see this apiVersion: apps/v1beta2, and in another apiVersion: apps/v1. Which one is correct? Which you should use? How to check which are supported on your Kubernetes cluster? Those are all valid questions and I will try to explain it using simple trick, the kubectl.

API Resources

You can get all API resources supported by your Kubernetes cluster using this command:

$ kubectl api-resources -o wide
NAME                              SHORTNAMES   APIGROUP                       NAMESPACED   KIND                             VERBS
bindings                                                                      true         Binding                          [create]
componentstatuses                 cs                                          false        ComponentStatus                  [get list]
configmaps                        cm                                          true         ConfigMap                        [create delete deletecollection get list patch update watch]
endpoints                         ep                                          true         Endpoints                        [create delete deletecollection get list patch update watch]
events                            ev                                          true         Event                            [create delete deletecollection get list patch update watch]
limitranges                       limits                                      true         LimitRange                       [create delete deletecollection get list patch update watch]
namespaces                        ns                                          false        Namespace                        [create delete get list patch update watch]
nodes                             no                                          false        Node                             [create delete deletecollection get list patch proxy update watch]
persistentvolumeclaims            pvc                                         true         PersistentVolumeClaim            [create delete deletecollection get list patch update watch]
persistentvolumes                 pv                                          false        PersistentVolume                 [create delete deletecollection get list patch update watch]
pods                              po                                          true         Pod                              [create delete deletecollection get list patch proxy update watch]
podtemplates                                                                  true         PodTemplate                      [create delete deletecollection get list patch update watch]
replicationcontrollers            rc                                          true         ReplicationController            [create delete deletecollection get list patch update watch]
resourcequotas                    quota                                       true         ResourceQuota                    [create delete deletecollection get list patch update watch]
secrets                                                                       true         Secret                           [create delete deletecollection get list patch update watch]
serviceaccounts                   sa                                          true         ServiceAccount                   [create delete deletecollection get list patch update watch]
services                          svc                                         true         Service                          [create delete get list patch proxy update watch]
mutatingwebhookconfigurations                  admissionregistration.k8s.io   false        MutatingWebhookConfiguration     [create delete deletecollection get list patch update watch]
validatingwebhookconfigurations                admissionregistration.k8s.io   false        ValidatingWebhookConfiguration   [create delete deletecollection get list patch update watch]
customresourcedefinitions         crd          apiextensions.k8s.io           false        CustomResourceDefinition         [create delete deletecollection get list patch update watch]
apiservices                                    apiregistration.k8s.io         false        APIService                       [create delete deletecollection get list patch update watch]
controllerrevisions                            apps                           true         ControllerRevision               [create delete deletecollection get list patch update watch]
daemonsets                        ds           apps                           true         DaemonSet                        [create delete deletecollection get list patch update watch]
deployments                       deploy       apps                           true         Deployment                       [create delete deletecollection get list patch update watch]
replicasets                       rs           apps                           true         ReplicaSet                       [create delete deletecollection get list patch update watch]
statefulsets                      sts          apps                           true         StatefulSet                      [create delete deletecollection get list patch update watch]
...

I trimmed the output as there are many of them. There is a lot of useful information here, let's explain some interesting ones:

  • SHORTNAMES - you can use those shortcuts with kubectl
  • APIGROUP - check the official docs to learn more, but in short, you will use it like this apiVersion: <APIGROUP>/v1 in yaml files
  • KIND - the resource name
  • VERBS - available methods, also useful when you want to define ClusterRole RBAC rules

You also have the option to get API resources for a particular API group, for example:

$ kubectl api-resources --api-group apps -o wide
NAME                  SHORTNAMES   APIGROUP   NAMESPACED   KIND                 VERBS
controllerrevisions                apps       true         ControllerRevision   [create delete deletecollection get list patch update watch]
daemonsets            ds           apps       true         DaemonSet            [create delete deletecollection get list patch update watch]
deployments           deploy       apps       true         Deployment           [create delete deletecollection get list patch update watch]
replicasets           rs           apps       true         ReplicaSet           [create delete deletecollection get list patch update watch]
statefulsets          sts          apps       true         StatefulSet          [create delete deletecollection get list patch update watch]

For each of those kinds you could use kubectl explain to get more info about the particular resource:

$ kubectl explain configmap
KIND:     ConfigMap
VERSION:  v1

DESCRIPTION:
     ConfigMap holds configuration data for pods to consume.

FIELDS:
   apiVersion	<string>
     APIVersion defines the versioned schema of this representation of an
     object. Servers should convert recognized schemas to the latest internal
     value, and may reject unrecognized values. More info:
     https://git.k8s.io/community/contributors/devel/api-conventions.md#resources

   data	<map[string]string>
     Data contains the configuration data. Each key must consist of alphanumeric
     characters, '-', '_' or '.'.

   kind	<string>
     Kind is a string value representing the REST resource this object
     represents. Servers may infer this from the endpoint the client submits
     requests to. Cannot be updated. In CamelCase. More info:
     https://git.k8s.io/community/contributors/devel/api-conventions.md#types-kinds

   metadata	<Object>
     Standard object's metadata. More info:
     https://git.k8s.io/community/contributors/devel/api-conventions.md#metadata

Please note that explain may show an old group/version, but you can explicitly set it with --api-version, for example, kubectl explain replicaset --api-version apps/v1. Thanks @markoluksa for the tip!

API Versions

You can also get all API versions supported by your cluster using this command:

$ kubectl api-versions
admissionregistration.k8s.io/v1beta1
apiextensions.k8s.io/v1beta1
apiregistration.k8s.io/v1beta1
apps/v1
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
certmanager.k8s.io/v1alpha1
enterprises.upmc.com/v1
events.k8s.io/v1beta1
extensions/v1beta1
metrics.k8s.io/v1beta1
monitoring.coreos.com/v1
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

The output is presented in form of "group/version". Check this page, to learn more about API versioning in Kubernetes.

Sometimes, you just want to check if a particular group/version is available for some resource. Most resources have available get method, so just try to get a resource while providing API version and group kubectl get <API_RESOURCE_NAME>.<API_VERSION>.<API_GROUP>. For example:

$ kubectl get deployments.v1.apps -n kube-system
NAME                                    DESIRED   CURRENT   UP-TO-DATE   AVAILABLE   AGE
autoscaler-aws-cluster-autoscaler       1         1         1            1           55d
calico-kube-controllers                 1         1         1            1           317d
calico-policy-controller                0         0         0            0           317d
dns-controller                          1         1         1            1           317d
elasticsearch-operator                  1         1         1            1           274d
hpa-hpa-operator                        1         1         1            1           60d
hpa-metrics-server                      1         1         1            1           60d
kube-dns                                2         2         2            2           317d
kube-dns-autoscaler                     1         1         1            1           317d
spot-rescheduler-k8s-spot-rescheduler   1         1         1            1           136d
tiller-deploy                           1         1         1            1           315d

You will get the error if the resource doesn't exist with specified group/version combination or if the resource doesn't exist at all.

Summary

This article will help you to understand what are those two lines in yaml, kind and apiVersion next time you see them. If you want to learn more about Kubernetes design I recommend checking this post. Stay tuned for the next one!