Don’t Memorize Kubernetes API Resources. Use These Two kubectl Commands Instead!

Austin Dewey
Jun 21, 2020 · 4 min read
Image for post
Image for post
Photo by John Schnobrich on Unsplash

How many times have you forgotten the name of a Kubernetes API resource you intended to create, view, or modify? Maybe you knew the name of the resource but forgot what the proper schema should be? Both of these scenarios happen to me all the time, especially for resources with longer names or for those I may not interact with daily.

For example, let’s pretend that you needed to create a new validating webhook. The ValidatingWebhookConfiguration resource would allow you to register this, but you may not know about this resource or remember its full name. Luckily, using the kubectl api-resources command, you could search through all of the registered API resources to find the right one.

Once you find the right resource, you would need to know the correct YAML schema so its configuration can be applied. Schemas can be lengthy and difficult to memorize. Luckily, you could use the kubectl explain command to find the full schema, which would help you write the declarative YAML without memorizing every detail.

In this post, I’ll explain the workflow I use to create Kubernetes API resources that involves as little memorization as possible. I first use kubectl api-resources to find the name of the resource if I’m unsure of its name. Then, I use kubectl explain to brush up on the resource’s schema so that I can create it.

Let’s first focus on kubectl api-resources.

Discovering API Resources with kubectl api-resources

The kubectl api-resources command prints each registered API resource. Below is a snippet from the output of this command.

Use kubectl api-resources to see registered API resources

Scrolling through to the middle of the output shows the ValidatingWebhookConfiguration resource mentioned earlier.

While searching through the full contents of this output is one way of interacting with this command, I prefer to pipe this output to grep if I know what I’m looking for to limit the number of results returned. For example, let’s say I’m searching for the ValidatingWebhookConfiguration resource, and I know the resource’s name includes the word “validating” but I don’t remember the rest. I can pipe the kubectl api-resources output to grep using the command kubectl api-resources | grep validating, shown below:

Grep output to narrow results

Since I grepped this output, I don’t need to search through the entire list of resources to determine the full name.

You can use this trick for any resource. Another good use case is for when you want to recall all of the API resources under a particular API group. For example, let’s say that you have Gatekeeper installed in your cluster. You can reveal each of the API resources required to interact with Gatekeeper by piping the kubectl api-resources output to grep, searching for the word “gatekeeper”:

Given this output, you would know that you need to work with Config, K8sRequiredLabels, and ConstraintTemplate resources to interact with your Gatekeeper installation.

While finding resources with kubectl api-resources will likely be a useful tool in your toolbox, you must also know their schemas to create them. The kubectl explain command can help with this, “explained” next.

Recalling Resource Schemas with kubectl explain

There are many different resources and schemas you must interact with when working in Kubernetes. Luckily, you don’t have to commit these to memory with the kubectl explain command.

Following the example from before, let’s say that after I found the ValidatingWebhookConfiguration resource, I wanted to start writing the YAML for it. I may know part of the YAML and just need a refresher on the remaining bits, or I may be seeing it for the first time. Either way, I can begin discovering the schema by running kubectl explain validatingwebhookconfiguration, shown below:

Use kubectl explain to see the high-level schema

This output displays the top-level fields of the schema. You can see that I need to provide the apiVersion, kind, metadata, and webhooks to configure this resource. To step into each of these fields, I need to pass in the recursive flag. Below is a snippet of output after using running kubectl explain validatingwebhookconfiguration --recursive.

Use kubectl explain with the recursive flag to see the detailed schema

Using this command, you can see the full schema down to the last child level. Scrolling to the end of this output is the complete “webhooks” field, which configures the webhook in a ValidatingWebhookConfiguration resource.

I use this all the time for both simple and complex resources. I can’t always remember the exact schemas, so I use kubectl explain with the --recursive flag to provide a quick reference from the command line.

You probably noticed that the kubectl explain --recursive command does not define each schema field — it simply outputs what the field is and its corresponding type. If you are unsure about how to configure a particular field, you’ll have to look through the Kubernetes documentation to learn more (or you can pass the field to kubectl explain — see my update below). The good thing, however, is that the schema itself will not be a mystery. You’ll be more familiar with what to look for once you get to the documentation.

Thanks for Reading!

I hope that you found this article to be helpful. I use the kubectl api-resources and kubectl explain commands all the time to recall resources that I haven’t memorized. Using these commands will save you a lot of time configuring your Kubernetes API resources.

Update: 7/31/2020

I previously mentioned that kubectl explain --recursive doesn’t provide any detailed descriptions of the output fields. Well, I recently learned a new trick that might save you a trip to documentation. After inspecting the output of kubectl explain validatingwebhookconfigurations --recursive, let’s say that you wanted to learn more about the webhooks.matchPolicy setting. It turns out you can pass this straight to kubectl explain and get a detailed description of the field by running this command:

kubectl explain validatingwebhookconfiguration.webhooks.matchPolicy

Here’s an example below:

If you want to learn more about a specific field, don’t run off to the documentation quite yet. Pass it to kubectl explain!

Originally published at https://austindewey.com on June 21, 2020.

The Startup

Medium's largest active publication, followed by +754K people. Follow to join our community.

Austin Dewey

Written by

Kubernetes enthusiast and not-terrible guitarist. Co-author of Learn Helm. | https://austindewey.com

The Startup

Medium's largest active publication, followed by +754K people. Follow to join our community.

Austin Dewey

Written by

Kubernetes enthusiast and not-terrible guitarist. Co-author of Learn Helm. | https://austindewey.com

The Startup

Medium's largest active publication, followed by +754K people. Follow to join our community.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store