A Beginner's Guide to YAML (or: How I Learned to Stop Worrying and Love the Indentation)

YAML stands for “YAML Ain’t Markup Language.” After writing your thousandth Kubernetes manifest, you may feel it stands for “Yet Another Mistake in the Layout.”

YAML is simultaneously the easiest and most frustrating configuration format ever created. It’s easy because it’s basically structured plain text. It’s frustrating because the difference between a working config and a three-hour debugging session is approximately one space character in column 7 of line 34.

The Rules (All Two of Them)

Rule 1: Indentation matters. Two spaces. Always two spaces. Not three. Not one. Not tabs. If you use tabs, YAML will reject you like a cat being offered a bath. Configure your editor to convert tabs to spaces before you write a single YAML file.

Rule 2: The dash-space combo is sacred. A list item in YAML is - value. Not -value. Not – value. Hyphen, space, value. This is the one true way.

That’s it. Those are the rules. And yet, somehow, these two rules spawn more Stack Overflow questions than any other topic in DevOps. Why? Because we forget them. Every single time.

Common YAML Disasters

The Phantom Array: You intended to write a nested object, but your indentation is off by one space, so YAML interprets it as a string. Your application receives "port: 8080\nhost: localhost" instead of an actual config object. Good luck debugging that.

The Boolean Trap: In YAML, yes, no, true, false, on, and off are all valid booleans. If you need a string “yes,” you must quote it. Otherwise YAML helpfully converts it. You’ll discover this when your country code “NO” becomes false and all your Norwegian customers mysteriously disappear.

The Anchor Overload: YAML anchors (&defaults) and aliases (*defaults) let you reuse config blocks. They also let you create self-referential nightmares that even the YAML parser doesn’t fully understand. Use with caution, or not at all.

The Survival Guide

1. Use a YAML linter. yamllint catches spacing issues before they hit production. Run it in your CI pipeline.
2. Use an editor with YAML support. VS Code with the YAML extension highlights indentation errors in real-time.
3. Never write YAML by hand if you can generate it. Tools like helm, kustomize, or even a simple script are better than manual typing.
4. When in doubt, quote it out. Strings that look like booleans, numbers, or nulls should always be quoted.
5. Check your spacing before committing. Two spaces. I cannot emphasize this enough. Two. Spaces.

YAML is the Latin of DevOps: nobody speaks it natively, everyone pretends to be fluent, and the best you can hope for is to make fewer mistakes than last month. Good luck. And watch your spacing.