Silly Kubectl Trick #1: EXPLAIN YOURSELF, KUBERNETES!

To say that Kubernetes uses a bit of YAML is like saying that a few people put some of their code on GitHub – accurate, but severely understated.

Kubernetes uses a LOT of YAML.

It takes over 50 lines of YAML to get a namespace with a single-container deployment with a service, no volumes, no secrets, and no configuration.

Keeping all that syntax straight can be daunting. Is that property a string or can it be a number? Does that collection get set as a map or a list? Who knows?

kubectl knows.

The online Kubernetes API Reference Documentation site is great, but kubectl can help us out here with its kubectl explain command:

kubectl explain pod.spec.containers

kubectl explain deployments.metadata 

kubectl explain secret.data

Each of these invocations will spit out documentation about the specified bits of Kubernetes resource YAML. I use it all the time to remember which API group/version a given object type exists in:

xxxxxxxxxx

$ kubectl explain statefulsets | head -n2 

KIND:     StatefulSet 

VERSION:  apps/v1

Did you know that the keys in a ConfigMap's data attribute must follow a strict format? Or that non-UTF-8 configuration values are supposed to go in a different top-level attribute altogether? kubectl explain does:

xxxxxxxxxx

$ kubectl explain configmap.data 

KIND:     ConfigMap 

VERSION:  v1 

FIELD:    data <map[string]string> 

DESCRIPTION:    

    Data contains the configuration data. Each key must consist of alphanumeric         characters, '-', '_' or '.'. Values with non-UTF-8 byte sequences must use the      BinaryData field. The keys stored in Data must not overlap with the keys in the     BinaryData field, this is enforced during validation process.

I have a tough time remembering what things are specified as lists, and what things are specified as keyed maps. Is a container's set of mounted volumes an array? An object? With explain, I don't have to remember:

x

kubectl explain pod.spec.containers.volumeMounts 

KIND:     Pod 

VERSION:  v1 

RESOURCE: volumeMounts <[]Object> 

DESCRIPTION:

    Pod volumes to mount into the container's filesystem. Cannot be updated.

    VolumeMount describes a mounting of a Volume within a container.    

... etc. ...

Note: Even though pod.spec.containers is a list, you don't have to worry about that when referencing through it to its sub-fields. This is in contrast to JSON path expressions and Go templates. It's so handy (and transparent!) that I had to point this out, explicitly!

Check Out the Video!

If you like that, check out the accompanying video, which goes into a bit more depth. Plus, you get to listen to the dulcet tones of me, your author.