How YAML Works: A Practical Guide for Automation

Last Updated: August 06, 2025

name: nginx
replicas: 3
debug: true

ports:
  - 80
  - 443

metadata:
  name: web
  labels:
    env: prod

apiVersion: v1
kind: Pod
metadata:
name: nginx
spec:
name: nginx
image: nginx:1.25

apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  name: nginx
  image: nginx:1.25

You may also encounter explicit type tags such as !!int or !!str which let you override YAML’s implicit typing, for example:

version: !!str 1.0

env-common: &common
  ENV: production
  LOG_LEVEL: info

services:
  app:
    environment: *common
  worker:
    environment: *common

Be mindful that anchors live within a single document. If you split a Helm chart into multiple files you cannot reference an anchor defined in another file unless the tool concatenates them first. Also remember that aliases do not create a deep copy; changing an aliased value later will mutate every node that refers to it, which can surprise readers. A safer pattern is to use anchors only for constant blocks and never rewrite them.

base: &base
  retries: 3
  timeout: 30

download:
  <<: *base
  url: https://example.com/file.tar.gz

? [ ubuntu, 22.04 ]
: lts

While exotic, complex keys occasionally shine in CI pipelines that need to map environment combos to images.

Literal (|) preserves newlines

script: |
  #!/usr/bin/env bash
  echo 'Hello'

Folded (>) wraps text into a single logical line separated by spaces

description: >
  This will become one long string
  with newlines replaced by spaces.

Flow mode wraps collections in square or curly braces, mirroring JSON, which can improve readability for small objects.

colors: [ red, green, blue ]
ports: { http: 80, https: 443 }

---
- name: Clean temp folder
  hosts: all
  gather_facts: false
  tasks:
    - name: Remove everything in /tmp
      file:
        path: /tmp
        state: absent

Run it

ansible-playbook -i inventory delete_temp.yml

Ansible connects to each host, removes /tmp, and then recreates the directory so that applications can continue to write temporary files. The idempotent nature of the file module ensures that repeated executions do not change state.

{
  "services": {
    "db": { "image": "postgres:16" }
  }
}

Convert it:

cat compose.json | yq -o=yaml > compose.yml

name: Build
on: [ push, pull_request ]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run unit tests
        run: make test

Commit and push. GitHub will queue the job automatically. If you prefer reproducibility, switch runs-on to ubuntu-22.04 so the image version does not move without notice.

• yamllint checks formatting and syntax
• kubeval validates Kubernetes manifests against the API schema
• ansible-lint catches playbook issues such as missing become
• conftest evaluates Open Policy Agent rules against any YAML

Combine these in a pre-merge pipeline. Example GitHub step:

- uses: frenck/action-yamllint@v1
  with:
    config_data: '{extends: relaxed}'

7. Common pitfalls and how to debug them

• Tabs instead of spaces
• Mixed indentation width
• Missing quotation marks on boolean-like words
• Dangling colons in strings
• Unintended type coercion (octal numbers)
• Duplicate keys sneaking past lenient parsers

When kubectl apply returns

error converting YAML to JSON: yaml: line 10: did not find expected key

pipe the file through yq eval -o json to pinpoint the line. Tools like stern and kubetail then trace runtime errors that stem from mis-typed environment variables.

Fill in your email on the landing page linked below and you will receive a printable A4 cheat sheet.