YAML looks tiny. Then it runs your builds, ships your app, configures your cluster, and wakes you up at 2 a.m. This cheatsheet makes YAML friendly. Think of it as a pocket map for developers and DevOps teams.

TLDR: YAML is a clean way to write configuration files using indentation, key value pairs, lists, and simple data types. It is used in tools like Kubernetes, Docker Compose, GitHub Actions, Ansible, and many CI/CD systems. Spaces matter, tabs are trouble, and comments are your best friend. If your YAML breaks, check indentation first.

What Is YAML?

YAML means YAML Ain’t Markup Language. Yes, it is a recursive joke. Developers love those.

YAML is made for data. It is easy for people to read. It is also easy for machines to parse. That is why DevOps teams use it everywhere.

You will find YAML in:

  • Kubernetes manifests
  • Docker Compose files
  • GitHub Actions workflows
  • GitLab CI pipelines
  • Ansible playbooks
  • Helm values files
  • Application config files

YAML is like a neat lunchbox. Everything has a place. If you put the sandwich in sideways, chaos may happen.

The Golden Rule: Spaces Matter

YAML uses indentation to show structure. Spaces are not decoration. They are the skeleton.

Use spaces. Do not use tabs. Tabs are tiny gremlins. They look helpful. Then they break production.

server:
  host: localhost
  port: 8080

In this example, host and port belong to server. They are children of that key.

A common style is two spaces per level. Some teams use four. Pick one. Stay consistent. Future you will clap softly.

Basic Key Value Pairs

The simplest YAML item is a key and a value.

name: api service
environment: production
debug: false

The key goes on the left. The value goes on the right. A colon separates them. Add a space after the colon.

Good:

port: 3000

Bad:

port:3000

That missing space can cause pain. Tiny pain. Then big pain.

Strings

Strings are text. YAML often lets you skip quotes.

app: checkout
team: platform
region: eu west

You can also use quotes. Use them when the value has special characters, starts with odd symbols, or could be misunderstood.

version: "1.0"
message: "hello: world"
enabled: "false"

Notice "false" is a string. But false without quotes is a boolean. This matters.

Numbers and Booleans

YAML understands numbers.

replicas: 3
timeout: 30
cpu: 2

It also understands booleans.

debug: true
cacheEnabled: false

For config files, be clear. If you want text, use quotes. If you want a real boolean, skip quotes.

Null Values

Sometimes a value is empty on purpose. YAML supports nulls.

databasePassword: null
backupTarget: ~
owner:

These all can mean “no value.” But team tools may treat them differently. Check your parser. Trust, but verify.

Lists

Lists use a dash. Each item gets its own line.

services:
  - api
  - worker
  - scheduler

This says services contains three items.

You can also make lists of objects.

containers:
  - name: api
    image: myapp:1.2
    ports:
      - 8080
  - name: worker
    image: worker:1.2

This is very common in Kubernetes and CI files. The dash starts an item. The indented keys belong to that item.

Nested Objects

YAML supports objects inside objects. This is where indentation becomes boss mode.

database:
  host: db local
  port: 5432
  credentials:
    username: admin
    password: secret

credentials lives inside database. username and password live inside credentials.

If this feels like folders, good. That is the idea.

Inline Lists and Objects

YAML also has compact inline syntax. It looks a bit like JSON.

ports: [80, 443, 8080]

labels: { app: api, tier: backend }

This is short. It can be handy. But do not overuse it. YAML is loved because it is readable. Do not turn it into a puzzle box.

Comments

Comments start with #. They explain things to humans. Humans are important. Especially tired humans.

# Number of application instances
replicas: 3

image: myapp:latest # Change this for releases

Use comments for context. Do not comment the obvious.

Good comment:

# Keep this at 1 during database migrations
replicas: 1

Less useful comment:

# This is the port
port: 8080

The port knows it is a port.

Multi Line Strings

YAML has special syntax for long text. Use | to preserve line breaks.

script: |
  echo "Starting deploy"
  npm install
  npm run build

This is useful for shell scripts, messages, certificates, and config blocks.

Use > to fold lines into one paragraph.

description: >
  This service handles payments.
  It must be monitored closely.

The folded version becomes one line with spaces. The pipe version keeps the line breaks.

Anchors and Aliases

YAML has a copy and paste power tool. It is called an anchor.

defaults: &defaults
  retries: 3
  timeout: 30

serviceA:
  <<: *defaults
  url: service a

serviceB:
  <<: *defaults
  url: service b

&defaults creates an anchor. *defaults reuses it. << merges it into another object.

This can reduce repetition. But be careful. Too many anchors can make a file feel haunted.

Multiple Documents in One File

YAML can store multiple documents in one file. Separate them with three dashes.

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: app config

---
apiVersion: v1
kind: Service
metadata:
  name: app service

This is common in Kubernetes. One file can define many resources. Very neat. Very powerful.

Common YAML Patterns

Here are patterns you will see often.

Kubernetes Style

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 2
  template:
    spec:
      containers:
        - name: web
          image: nginx:latest

Lots of nesting. Lots of structure. Indentation is the map.

Docker Compose Style

services:
  web:
    image: nginx
    ports:
      - "8080:80"
  redis:
    image: redis

Notice the port is quoted. That avoids confusion with special parsing.

GitHub Actions Style

name: test

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Run tests
        run: npm test

CI YAML often mixes lists, objects, and scripts. Read it top to bottom. It is a recipe.

YAML Gotchas

YAML looks simple. It has traps. Small traps. Sneaky traps.

  • Tabs are bad. Use spaces only.
  • Indentation must match. One extra space can break meaning.
  • Colons need care. Quote strings that contain :.
  • Booleans can surprise you. Use quotes for string values like "true".
  • Empty values may become null. Be intentional.
  • Duplicate keys are dangerous. Some parsers allow them. Some overwrite them.
  • Special characters need quotes. When in doubt, quote.

A Tiny Debugging Checklist

When YAML fails, do not panic. Breathe. Then check this list.

  1. Did you use spaces instead of tabs?
  2. Is every nested level aligned?
  3. Is there a space after each colon?
  4. Are strings with special characters quoted?
  5. Are list items under the correct parent?
  6. Did you accidentally duplicate a key?
  7. Did your tool expect a specific schema?

Most YAML bugs are indentation bugs wearing a fake mustache.

Best Practices for Teams

Good YAML is boring. Boring is great. Boring deploys at 5 p.m. and lets everyone go home.

  • Use a formatter. Let tools fix spacing.
  • Use a linter. Catch errors before CI does.
  • Keep files small. Split giant configs when possible.
  • Name things clearly. Future readers are teammates.
  • Comment why, not what. Explain decisions.
  • Validate against schemas. Especially for Kubernetes and CI.
  • Avoid too much magic. Anchors are useful, but mystery is not.

Quick Cheatsheet

Need YAML Example
Key value name: app
String version: "1.0"
Number replicas: 3
Boolean enabled: true
Null value: null
List - item
Comment # hello
Multi line script: |

Final Thoughts

YAML is not scary. It is just strict about whitespace. Once you respect the spaces, it becomes a calm and useful friend.

For developers, YAML is the language of app settings and workflows. For DevOps teams, it is the language of infrastructure, pipelines, and automation. Learn the basics well. Quote when unsure. Lint before you ship. And remember the ancient law of YAML: when in doubt, check the indentation.