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>/v1in yaml files - KIND - the resource name
- VERBS - available methods, also useful when you want to define
ClusterRoleRBAC 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#metadataPlease 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
v1The 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 315dYou 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!