This site uses cookies and by using the site you are consenting to this. We utilize cookies to optimize our brand’s web presence and website experience. To learn more about cookies, click here to read our privacy statement.

Use These Resources to Help Stay Current with Kubernetes APIs

Author: Zachary Loeber Posted In: Cloud, DevOps

Can you quickly list out all the available pod security policy attributes on Kubernetes? How about listing the autoscaling apiVersions along with their spec attributes? If you are authoring any form of declarative manifest for configuring a Kubernetes cluster once it is running, these tasks are not uncommon. But with each version of Kubernetes, a new API schema is born. What may have worked only a year ago is on the road to depreciation — or worse, it’s already depreciated.

I found the simple task of getting API versions for resources to be both straightforward to perform but still oddly difficult to consume. It took digging through arcane swagger specifications and weird tools just to find out how to get this seemingly basic information. This is a small post on some additional resources you have for to obtain this information.

Concepts of Kubernetes API

Before diving into this post it would be wise to first give this concepts guide on the Kubernetes API a once over. It describes how the Kubernetes API is defined. If you are already prolific at reading swagger definition files, then you can simply go to the Kubernetes version you wish to look up, and parse that (See References at the end of this article).
Here’s a quick rundown: The API is broken down into a handful of resource categories that contain resource objects, which then provide specific API driven operations. Check out this table:
CategoryScopeExample Resource Objects
WorkloadsNamespaceJob, Pod, Deployment, Container, StatefulSet
ServicesNamespaceEndpoint, Ingress, Service
Config & StorageNamespace & ClusterConfigMap, Secret, StorageClass, PersistentVolumeClaim
ClusterNamespace & ClusterClusterRole, ClusterRoleBinding, Node, Namespace, NetworkPolicy
MetadataClusterHorizontalPodAutoscaler, Event, PodTemplate, PodSecurityPolicy, MutatingWebhookConfiguration, CustomResourceDefinitio
I was tempted to remove the “scope” column in this table as there is not a clear cut line between these groupings and the scope of their resources. There IS a general scope of namespaced vs. non-namespaced (non-namespaced =~ cluster level) at a per-resource level though and these scope approximations. The ‘kubectl api-resources’ command even has a flag appropriately called ‘–namespaced’.
# View all available resources which are not 'namespaced'
kubectl api-resources --namespaced=false
NOTE: The Kubernetes API also has a notion of ‘groups’ that is discussed in more detail here. The categories mentioned above are not related to the above API groups.

Finding Kubernetes resources

Finding available Kubernetes resources is relatively easy to do against a running cluster. But what about for an arbitrary version of Kubernetes? The swagger definition for a released version of Kubernetes is easy enough to find and even read, but it also uses references that can lead you down a rabbit hole of paths even for the simplest resources. Luckily, someone has already run into this particular issue and put a project out there to make working with the Kubernetes schema easier. This is done by normalizing the swagger API definition into JSON Schema.
The service offers a handful of options for pulling the JSON schema for individual elements. There is a standalone version which de-references the schema to put all resource elements in one spot. This is what I’ve been using and it works very well.
For instance, if you want to view the Service object for Kubernetes 1.18.1, in full, just go to https://kubernetesjsonschema.dev/v1.18.1-standalone/service-v1.json in your browser. In any modern browser the JSON payload will be easy to browse without much extra effort.
JSON schema for kubernetes service
JSON schema for Kubernetes service

Answering the questions

This post asked two questions. One of them is; Can you list out all the api versions for the autoscaling resources you can use on your cluster? This one is the easiest to answer. Use ‘kubectl api-versions’
kubectl api-versions | grep autoscaling
kubectl api-versions
kubectl api-versions
Why is this important? Because the difference between these three resources really determines how you will be able to autoscale your resources. Also, that only shows the version available for the resource at a generic level, which is only a small part of how you might author a manifest. Let’s take it further.
kubectl api-resources | grep autoscaling
kubectl api-resources
kubectl api-resources
This tells us that the kind of resource we can use this against is the horizontalpodautoscaler. Let’s use this and the prior resource to get its definition so we can try to create one of these things using the most recent version found for our cluster (v2beta2) – horizontalpodautoscaler-autoscaling-v2beta2 on Kubernetes 18.0
NOTE: Need to get your Kubernetes version? ‘kubectl get nodes’ should show you that one.
We can also simply pull in the resource from their repo in raw JSON format. This generic script is to download the JSON schema. Use any number of open source tools to convert to yaml or markdown if that suits your fancy.
tempdir=`mktemp -d`
curl --retry 3 --retry-delay 5 --fail -sSL -o ${tempdir}/${KIND}-${RESOURCE}-${RESOURCEVERSION}.schema.json https://raw.githubusercontent.com/instrumenta/kubernetes-json-schema/master/v${KUBEVER}-standalone/${KIND}-${RESOURCE}-${RESOURCEVERSION}.json

The Kubernetes API is an ever changing multi-headed hydra. But since it has a well-defined schema intrepid, developers and hackers have come up with good helper interfaces for getting information out of it more effectively.

Additional Resources