Use These Resources to Help Stay Current with Kubernetes APIs
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:
| Category | Scope | Example Resource Objects |
| Workloads | Namespace | Job, Pod, Deployment, Container, StatefulSet |
| Services | Namespace | Endpoint, Ingress, Service |
| Config & Storage | Namespace & Cluster | ConfigMap, Secret, StorageClass, PersistentVolumeClaim |
| Cluster | Namespace & Cluster | ClusterRole, ClusterRoleBinding, Node, Namespace, NetworkPolicy |
| Metadata | Cluster | HorizontalPodAutoscaler, 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.
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
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
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.
KUBEVER=1.18.0
KIND=horizontalpodautoscaler
RESOURCE=autoscaling
RESOURCEVERSION=v2beta2
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}.jsonThe 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.