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.containerskubectl 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:

$ 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:

$ 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:

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.