Last update: November 30, 2018

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

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!