Master YAML in 2024: Complete Learning Guide for DevOps Engineers

# Basic data types
app_name: FocusPilot        # String
version: 1.0                # Number
active: true                # Boolean
null_field: null            # Null
description: "Browser productivity copilot"  # Quoted string

numbers:
  decimal: 42
  hex: 0x2A
  octal: 052
  float: 3.14
  exponential: 1e+5

# Boolean variants (all valid)
truthy: [true, True, YES, On]
falsy: [false, False, NO, Off]
null_variants: [null, Null, ~]

single_line: "Hello, YAML!"

# Literal style - preserves newlines
multi_line_literal: |
  Line 1
  Line 2
  Line 3

# Folded style - joins lines
multi_line_folded: >
  This long text
  becomes one
  single paragraph.

# Block style
languages_block:
  - JavaScript
  - TypeScript
  - Python
  - Go

# Flow style (inline)
languages_inline: [Rust, Java, C++]

# Nested lists
teams:
  - name: Frontend
    members: ["Alice", "Bob"]
  - name: Backend
    members: ["Charlie", "David"]

developer:
  name: Yuvraj Karna
  role: Software Engineer
  skills:
    - DevOps
    - Kubernetes
    - YAML
  social:
    github: "yuvrajkarna2717"
    linkedin: "in/yuvrajkarna27"

# Define reusable content with &
defaults: &default_settings
  retries: 3
  timeout: 30
  verbose: true

# Reuse with * and merge with <<:
dev_env:
  <<: *default_settings
  url: dev.example.com
  timeout: 10  # Override specific values

prod_env:
  <<: *default_settings
  url: example.com
  timeout: 60

base_config: &base
  app: MyApp
  database:
    host: localhost
    port: 5432

# Shallow merge - entire database object replaced
production:
  <<: *base
  database:
    host: prod.example.com
    # port is lost! Only host remains

# Block style (recommended for readability)
users_block:
  - name: John
    age: 30
    active: true
  - name: Jane
    age: 25
    active: false

# Flow style (compact)
users_flow: [{name: John, age: 30}, {name: Jane, age: 25}]

# Document 1: Service
---
apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  ports:
    - port: 80
      targetPort: 3000

# Document 2: Deployment
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: app
          image: nginx:alpine

env:
  NODE_ENV: production
  PORT: 8080
  DATABASE_URL: "postgresql://user:pass@localhost/db"

# Reference environment variables (tool-specific)
config:
  database_url: ${DATABASE_URL}
  debug: ${DEBUG:-false}  # Default value

# Ansible
secret_key: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  encrypted_content_here

# Kubernetes
data:
  config.yaml: |
    key: value

# Docker Compose
services:
  app:
    environment:
      - SECRET=!secret app_secret

# Complex keys (rarely used)
? [name, role]
: ["Yuvraj", "Engineer"]

? {x: 10, y: 20}
: "Coordinates"

# Type casting
string_number: !!str 123
int_string: !!int "456"
bool_string: !!bool "true"

# Reusable labels
labels: &app_labels
  app: focuspilot
  version: v1.2.0
  environment: production

# Service
apiVersion: v1
kind: Service
metadata:
  name: focuspilot-service
  labels: *app_labels
spec:
  selector: *app_labels
  ports:
    - port: 80
      targetPort: 3000

---
# Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: focuspilot-deployment
  labels: *app_labels
spec:
  replicas: 3
  selector:
    matchLabels: *app_labels
  template:
    metadata:
      labels: *app_labels
    spec:
      containers:
        - name: app
          image: focuspilot:v1.2.0
          ports:
            - containerPort: 3000

# Base configuration
x-app-base: &app_base
  restart: unless-stopped
  networks:
    - app_network
  environment:
    - NODE_ENV=production

# Environment-specific configs
x-logging: &logging
  logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "3"

services:
  web:
    <<: [*app_base, *logging]
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf

  api:
    <<: [*app_base, *logging]
    image: node:18-alpine
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/app

  db:
    <<: *logging
    image: postgres:15
    environment:
      - POSTGRES_DB=app
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

networks:
  app_network:

# Common variables
vars: &common_vars
  app_name: focuspilot
  app_version: "1.2.0"
  app_port: 3000

# Playbook
- name: Deploy Application
  hosts: webservers
  vars: *common_vars
  tasks:
    - name: Create app directory
      file:
        path: "/opt/{{ app_name }}"
        state: directory
        mode: '0755'

    - name: Deploy application
      docker_container:
        name: "{{ app_name }}"
        image: "{{ app_name }}:{{ app_version }}"
        ports:
          - "{{ app_port }}:{{ app_port }}"
        restart_policy: unless-stopped

# Reusable job configuration
x-node-setup: &node_setup
  - uses: actions/checkout@v3
  - uses: actions/setup-node@v3
    with:
      node-version: '18'
      cache: 'npm'

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      <<: *node_setup
      - run: npm ci
      - run: npm test

  build:
    runs-on: ubuntu-latest
    needs: test
    steps:
      <<: *node_setup
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v3
        with:
          name: build-files
          path: dist/

# Use consistent indentation (2 or 4 spaces)
config:
  database:
    host: localhost
    port: 5432

# Quote strings with special characters
password: "p@ssw0rd!"
version: "1.0"  # Prevent interpretation as number

# Use anchors for reusability
defaults: &defaults
  timeout: 30
  retries: 3

services:
  api: 
    <<: *defaults
    port: 3000

# DON'T mix tabs and spaces
config:
    host: localhost  # 4 spaces
    port: 5432       # tab - WILL BREAK!

# DON'T use unquoted special values
version: 1.0       # Becomes float
version: "1.0"     # Stays string

# DON'T forget YAML is case-sensitive
active: True       # String "True"
active: true       # Boolean true

# Install yq for validation
pip install yq
# or
brew install yq

# Validate syntax
yq eval your-file.yaml

# Convert to JSON to verify structure
yq -o json your-file.yaml

# For scripts (preserve newlines)
install_script: |
  #!/bin/bash
  apt-get update
  apt-get install -y docker

# For descriptions (fold lines)
description: >
  This is a very long description
  that spans multiple lines but
  will be joined into one paragraph.

# Base configuration
base: &base
  image: myapp
  restart: unless-stopped

# Environment overrides
development:
  <<: *base
  image: myapp:dev
  environment:
    - DEBUG=true

production:
  <<: *base
  image: myapp:latest
  replicas: 3
  environment:
    - DEBUG=false

# | preserves newlines exactly
script: |
  line 1
  line 2
# Result: "line 1\nline 2\n"

# > folds lines into single paragraph
description: >
  line 1
  line 2
# Result: "line 1 line 2\n"

# All these are boolean true
valid_true: [true, True, TRUE, yes, Yes, YES, on, On, ON]

# All these are boolean false
valid_false: [false, False, FALSE, no, No, NO, off, Off, OFF]

name: John
age: 30
name: Jane  # This overwrites the first name
# Result: name = "Jane", age = 30

base: &base
  app: MyApp
  config:
    debug: false
    timeout: 30

# Shallow merge - entire config object replaced
dev:
  <<: *base
  config:
    debug: true
    # timeout is LOST! Only debug remains

# Correct way - merge nested objects too
dev_correct:
  <<: *base
  config:
    <<: *base.config
    debug: true  # Now timeout is preserved

single: 'No escape sequences: \n \t'
double: "Escape sequences work: \n \t"
unquoted: Plain text, but 123 becomes number

# ❌ Never do this
password: mySecretPassword123

# ✅ Use environment variables
password: ${DB_PASSWORD}

# ✅ Use external secret management
password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  encrypted_content_here

# ✅ Reference Kubernetes secrets
env:
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: db-secret
        key: password

# Complex keys (rarely used in practice)
? [name, role]
: ["John", "Developer"]

? {service: web, port: 80}
: "Web server configuration"

# Most parsers convert these to strings
# Better to use nested structure instead

# Explicit type casting
version: !!str 1.0      # Force string
port: !!int "8080"      # Force integer

# Tool-specific tags
secret: !secret "encrypted_value"     # Ansible Vault
template: !template "{{ variable }}"   # Jinja2
include: !include "other-file.yaml"    # File inclusion

# Install yq (YAML processor)
pip install yq
# or
brew install yq

# Validate YAML
yq eval your-file.yaml

# Convert YAML to JSON
yq -o json your-file.yaml

# Format YAML
yq -P eval your-file.yaml

# Extract specific values
yq '.services.web.ports[0]' docker-compose.yaml

# Install yq for validation
pip install yq
# or
brew install yq

# Validate your YAML
yq eval your-file.yaml

# Use anchors for environment overrides
defaults: &defaults
  replicas: 1
  resources:
    requests:
      memory: "64Mi"

production:
  <<: *defaults
  replicas: 3
  resources:
    requests:
      memory: "256Mi"