Kubernetes Explained Simply: #1 Kubectl Hack

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:

$ 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 no longer 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!

If you like that, check out the accompanying video which goes into a bit more depth:

The next tip will help you figure out what images you're running in production.

Previously published at https://www.starkandwayne.com/blog/silly-kubectl-trick-1-explain-yourself-kubernetes/