Most people find it hard to get their heads around Kubernetes YAML. This is normal and nothing to be ashamed of. Fortunately… once you get your head around it, it’s pretty simple.
So here goes with a few ways to get yourself comfortable with Kubernetes YAML files.
Never create from scratch
People always ask me if I’ve got any resources for writing YAML files.
The answer is “no”. And the reason is simple… I almost never write YAML from scratch. I always copy an old file and tweak it for my current requirement.
I’ve been doing Kubernetes for a while now, so I’ve got a decent store of YAML files that can I can re-use and tweak. But if you’re new, just Google whatever you need.
Extract a YAML from your cluster
Another way to get an existing YAML file is from existing Kubernetes clusters.
Every Kubernetes cluster comes with a bunch of objects in the kube-system Namespace. You can extract the YAML for any of these with kubectl get <object> <name> -n kube-system -o yaml. For example, the following command will extract the full YAML file for a StatefulSet object called nfs-provisioner in the kube-system Namespace.
$ kubectl get sts nfs-provisioner -n kube-system -o yaml
You can use the returned YAML as the basis for a new StatefulSet YAML file. You can also inspect it and learn some of the more advanced properties that you can set on a StatefulSet object.
If you use this YAML as the basis of a new YAML file, you’ll need to delete the status section.
A few words on Kubernetes YAML format
Almost all Kubernetes YAML files have the following four top-level sections:
kind:
apiVersion:
metadata:
spec:
kind tells Kubernetes what type of object is being defined (Pod, Deployment, ConfigMap etc.) and apiVersion specifies the schema version of the object. metadata is where you give the object a name, as well as apply labels and annotations. The spec section is where the object is actually defined.
Every property is defined as a key:value pair. The key portion is immediately followed by a colon, and then one whitespace before the value.
Keys are written in lower camel case (the initial letter is not capitalised) and values are written in upper camel case (the initial letter is capitalised). For example:
apiVersion: apps/v1
kind: StatefulSet
You should always use two spaces for each level of indentation. For example:
- Single level of indentation: 2 white spaces
- Two levels of indentation: 4 white spaces
- Three levels of indentation: 6 white spaces
Use a code editor
My final piece of advice is two write and modify your Kubernetes YAML files with a code editor that has a Kubernetes or a YAML plugin. I use VS Code.
Using an editor like this gives great features such as tab completion, colour coding, and a linter that highlights potential errors and misconfigurations.
Where to learn the Fundamentals of Kubernetes YAML
MSB.com has some great content on writing Kubernetes YAML.
The platform has some features that make it really easy to learn the structure and properties of Kubernetes YAML.
For example, the image to the left shows the mouse cursor hovering over the description of some YAML. At the same time, the correct lines of the YAML file are highlighted below.
This can be extremely powerful when explaining YAML files — it’s really simple to see which lines and blocks of YAML are being referred to.
It also has hands-on labs for writing and deploying YAML files.
Happy YAML writing!
