What Is YAML? Explained for Beginners (2026)

YAML is the config language of DevOps — Kubernetes, Docker Compose, GitHub Actions, Ansible all use it. Here's what YAML actually is and how to read and write it without confusion.

YAML is everywhere in DevOps. Kubernetes manifests, Docker Compose, GitHub Actions, Helm charts, Ansible playbooks — all YAML. Here's how to understand it properly.

What YAML Is

YAML (YAML Ain't Markup Language) is a human-readable data serialization format. It's used for configuration files because it's cleaner to read than JSON and doesn't require the brackets and quotes that JSON needs.

Same data in JSON vs YAML:

json

{
  "name": "my-app",
  "version": "1.0",
  "replicas": 3,
  "enabled": true
}

yaml

name: my-app
version: "1.0"
replicas: 3
enabled: true

YAML wins on readability, especially for long configuration files.

YAML Basics

Key-Value Pairs

yaml

# Basic key: value
name: devopsboys
port: 8080
debug: false

Strings

yaml

# Most strings don't need quotes
name: my-application
 
# Use quotes when string has special characters or starts with numbers
version: "1.0"
message: "Hello: World"   # colon in string needs quotes
tag: "123abc"             # starts with number, use quotes
 
# Multi-line strings
description: |
  This is a multi-line
  string that preserves
  line breaks.
 
config: >
  This is a folded string
  where line breaks become
  spaces.

Numbers and Booleans

yaml

port: 8080          # integer
ratio: 0.75         # float
enabled: true       # boolean
disabled: false     # boolean
count: null         # null value

Watch out: YAML treats yes, no, on, off as booleans in some parsers. Always use true/false to be safe.

Lists (Arrays)

yaml

# Block style (most readable)
fruits:
  - apple
  - banana
  - cherry
 
# Inline style
fruits: [apple, banana, cherry]
 
# List of objects
servers:
  - name: web-01
    ip: 10.0.0.1
  - name: web-02
    ip: 10.0.0.2

Nested Objects (Maps)

yaml

# Nested with indentation (2 spaces standard)
database:
  host: localhost
  port: 5432
  name: mydb
  credentials:
    username: admin
    password: secret
 
# Inline (for simple cases)
database: {host: localhost, port: 5432}

Indentation — The Most Common Mistake

YAML uses spaces, not tabs for indentation. Using tabs will break your YAML.

Standard is 2 spaces per level. Some tools use 4, but 2 is most common in DevOps tools.

yaml

# CORRECT — 2 spaces
spec:
  containers:
  - name: my-app
    image: nginx:latest
    ports:
    - containerPort: 80
 
# WRONG — tabs cause parse errors
spec:
	containers:   # ← tab here will fail

The most common YAML error is inconsistent indentation. Always use a YAML validator (yamllint, or the validator in your IDE).

Comments

yaml

# This is a comment
name: my-app  # inline comment
 
# Multi-line comment:
# Line one
# Line two

Real-World Examples

Docker Compose

yaml

version: '3.8'
services:
  web:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
    environment:
      - NGINX_HOST=localhost
  
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: mypassword
      POSTGRES_DB: mydb
    volumes:
      - db-data:/var/lib/postgresql/data
 
volumes:
  db-data:

Kubernetes Deployment

yaml

apiVersion: apps/v1     # API version
kind: Deployment        # resource type
metadata:               # metadata about the resource
  name: my-app          # resource name
  namespace: default
  labels:               # labels are key-value pairs
    app: my-app
spec:                   # desired state
  replicas: 3           # run 3 copies
  selector:
    matchLabels:
      app: my-app
  template:             # pod template
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-app            # container name
        image: nginx:latest     # Docker image
        ports:
        - containerPort: 80     # exposed port
        resources:
          requests:
            memory: "64Mi"
            cpu: "100m"
          limits:
            memory: "128Mi"
            cpu: "500m"

GitHub Actions

yaml

name: CI Pipeline       # workflow name
 
on:                     # trigger conditions
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:                   # list of jobs
  test:                 # job name
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4     # pre-built action
    - name: Run tests               # custom step
      run: |                        # multi-line command
        pip install -r requirements.txt
        pytest tests/

Common YAML Errors and Fixes

"mapping values are not allowed here"

yaml

# WRONG
name:my-app     # missing space after colon
 
# CORRECT
name: my-app

"could not find expected ':'"

yaml

# WRONG (tabs used)
spec:
	replicas: 3   # tab indentation
 
# CORRECT (spaces)
spec:
  replicas: 3   # 2 spaces

"found character '\t' that cannot start any token" → Replace all tabs with spaces. In VS Code: Edit → Replace, enable Regex, find \t, replace with two spaces.

String parsed as number or boolean

yaml

# "1.0" without quotes becomes float
version: 1.0       # parsed as number 1.0
version: "1.0"     # parsed as string "1.0"
 
# "yes" without quotes becomes boolean
answer: yes        # parsed as true
answer: "yes"      # parsed as string "yes"

YAML Tips for DevOps

Use a linter:

bash

# Install yamllint
pip install yamllint
 
# Lint a file
yamllint my-config.yaml
 
# Lint a Kubernetes manifest
kubectl apply --dry-run=client -f deployment.yaml

VS Code extensions:

"YAML" by Red Hat — syntax highlighting, validation, Kubernetes schema
"Kubernetes" by Microsoft — validates K8s manifests against schema

Online validator: yamllint.com — paste your YAML and check instantly.

Anchors (advanced — avoid unless needed):

yaml

# Define a reusable block
defaults: &defaults
  image: alpine:latest
  pullPolicy: IfNotPresent
 
# Reuse it
container1:
  <<: *defaults   # merges defaults here
  name: app
 
container2:
  <<: *defaults
  name: worker

YAML in One Sentence

YAML is a human-readable configuration format that uses indentation to represent structure — it's the universal language of DevOps tools, and learning to read it fluently is essential for working with Kubernetes, Docker, GitHub Actions, and almost every other modern infrastructure tool.

If YAML ever confuses you, paste it into yamllint.com — the error message will point exactly to the problem.

What Is YAML? Explained for Beginners (2026)

What YAML Is

YAML Basics

Key-Value Pairs

Strings

Numbers and Booleans

Lists (Arrays)

Nested Objects (Maps)

Indentation — The Most Common Mistake

Comments

Real-World Examples

Docker Compose

Kubernetes Deployment

GitHub Actions

Common YAML Errors and Fixes

YAML Tips for DevOps

YAML in One Sentence

Stay ahead of the curve

Related Articles

DevOps Engineer Career Progression: Junior to Senior (2026 Roadmap)

7 DevOps Resume Mistakes That Get You Rejected (And How to Fix Them)

How to Contribute to Open Source as a DevOps Engineer (2026 Guide)

Comments