TL;DR: In this article, you will learn tips and gotchas for writing YAML manifests for Kubernetes resources.

YAML has three basic rules:

1. Indentation — only 2 or 4 spaces
2. Maps — key-value pairs
3. Lists — collections of things

Let’s start with the first.

A YAML file uses spaces as indentation; you can use 2 or 4 spaces but no tab.

Why no tabs?

It’s in the official YAML website FAQ.

Maps let you associate key-value pairs.

Maps can be nested, and in Kubernetes, you usually nest a lot of maps!

YAML lists are a sequence of objects.

You can have virtually any number of items in a list, defined as items that start with a dash - indented from the parent.

Maps and lists are the basic building blocks of any YAML file.

Any list or map’s value can be a string, a number, a boolean, null, or another dictionary or list.

In most cases, strings don’t require quotes.

But sometimes if you miss them… 💣💥

Listing countries?

Watch out for “the Norway problem!”

By default, the word “yes” and “no” are converted into booleans.

Are you setting the version of a library without quotes?

YAML automatically converts it to a number!

And YAML automatically converts a date to a timestamp.

In this case 4h * 60m * 60s + 30m * 60s = 16200s.

While keys in JSON are always strings, in YAML, they can be any value, including booleans.

Having on as a key is a terrible idea.

Apart from edge cases, there are some actual valuable features if you write Kubernetes manifests:

• You can use --- to delimit docs
• You can define snippets with * and reference them with &

YAML definitions in the same document can be separated using the --- operator.

A YAML file is terminated with ... (3 dots).

In YAML, you can define structures and assign them labels using the & operator.

You can recall the structure with the * operator and the label name when you wish to reuse it.

Read more here https://yaml.org/spec/1.2/spec.html#id2760395.

What if you make a mistake?

How do you know? 🤔

You could use:

1. an online YAML linter like http://www.yamllint.com/
2. a CLI like https://yamllint.readthedocs.io/en/stable/
3. if you use Visual Studio Code, install the YAML extension from Red Hat for autocomplete https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml

Is there any useful tool to edit YAML other than by hand?

yq is a command-line tool designed to transform YAML.

It is similar to another popular tool called jq that focuses on JSON instead of YAML.

# Read a value
yq 'spec.containers[0].env[0].value' pod.yaml

# Write a value
yq '.metadata.name = "learnk8s"' pod.yaml

# Merging two YAML files
yq '. *+ load("proxy.yaml")' app.yaml

# Output a YAML file as JSON
yq --tojson sample.yaml

That’s it!

Do you know more tips? Let me know in the comments!

And finally, if you’ve enjoyed this thread, you might also like the Kubernetes workshops that we run at Learnk8s https://learnk8s.io/training or this collection of past Twitter threads https://twitter.com/danielepolencic/status/1298543151901155330

Until next time!