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?
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 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.