Table of Contents
Why YAML Matters in DevOps
In DevOps tools on Linux (GitHub Actions, GitLab CI, Ansible, Kubernetes, etc.), configuration is very often written in YAML. Understanding just enough YAML syntax prevents many frustrating, hard‑to‑spot errors.
YAML is:
- Human-readable
- Structured (hierarchical)
- Whitespace-sensitive (indentation matters)
This chapter focuses on the essential YAML syntax you’ll actually see in DevOps tooling.
YAML Building Blocks: Scalars, Lists, Maps
YAML data is built from three core pieces:
- Scalars – single values (string, number, boolean, null)
- Lists – ordered sequences
- Maps (dictionaries) – key–value mappings
A typical YAML file mixes these:
name: my-app # scalar
replicas: 3 # scalar (number)
enabled: true # scalar (boolean)
containers: # list of maps
- name: web
image: nginx:latest
ports:
- 80
- 443
- name: api
image: my-api:1.0Scalars (Strings, Numbers, Booleans, Null)
Plain strings
Most strings in DevOps YAML are written plainly, without quotes:
image: ubuntu:22.04
branch: mainYAML tries to “guess” types:
true,false→ booleansnull,~→ null- Unquoted numbers like
42,3.14→ numbers
If you want a string that looks like a boolean or number, quote it:
version: "1.0" # string, not number
enabled: "false" # string "false", not boolean false
id: "000123" # leading zeros preservedQuoted strings
- Single quotes
'...'– literal text, only''is an escaped single quote. - Double quotes
"..."– support escape sequences like\n,\t.
path: "/usr/local/bin"
message: "Line1\nLine2" # contains a newline character
literal: 'C:\temp\' # good for Windows-style pathsBooleans and null
Be explicit to avoid surprises:
flag_true: true
flag_false: false
unset: null
also_unset: ~Lists (Sequences)
Lists are ordered collections. YAML has two main styles.
Block-style lists (most common)
Each item starts with - and a space:
packages:
- git
- curl
- htopList items can be scalars, maps, or other lists:
env:
- name: ENVIRONMENT
value: production
- name: DEBUG
value: "false"Inline lists
Short one-liners use square brackets:
ports: [80, 443]
branches: [main, develop, feature-x]Inline form is fine for small, simple lists; block style is more readable for complex structures.
Maps (Dictionaries / Key–Value Pairs)
Maps associate keys with values:
metadata:
name: my-app
namespace: production
labels:
app: web
tier: frontendIndentation groups nested maps. Keys are case-sensitive.
Inline maps (less common) use braces:
metadata: { name: my-app, namespace: production }Indentation and Whitespace Rules
Indentation is critical in YAML. Most DevOps tools expect two spaces per level.
- Use spaces only, no tabs.
- Items at the same level must have the same indentation.
- Child items are indented more than their parent.
Example:
job:
name: build-and-test # 2 spaces under 'job'
runs-on: ubuntu-latest
steps:
- name: Checkout # 4 spaces total (2 for 'steps' level, 2 for '-')
uses: actions/checkout@v3
- name: Run tests
run: make testIndentation errors are among the most common YAML mistakes.
Comments
Use # for comments. Anything after # on a line (outside of quotes) is ignored:
# This is a full-line comment
replicas: 3 # this is an end-of-line commentDon’t put comments inside quotes unless they are part of the string.
Multi-Line Strings
Sometimes you need readable multi-line text (scripts, descriptions, etc.). YAML provides two block scalar styles: literal and folded.
Literal block (`|`) – keep line breaks
YAML preserves line breaks exactly:
script: |
echo "Starting job"
make build
make test
The value of script is the three lines including newlines, often used in CI pipelines or Kubernetes manifests.
Folded block (`>`) – wrap into a single line
Line breaks become spaces (except for blank lines, which keep paragraph breaks):
description: >
This pipeline builds and tests the project.
It runs on every push to main.Equivalent to:
description: "This pipeline builds and tests the project. It runs on every push to main.\n"Controlling trailing newlines and indentation
You might see |+, |-, >+, >-:
-strip final newline+keep all trailing newlines
Example:
message: |-
line1
line2Anchors and Aliases (Avoiding Duplication)
YAML can reuse blocks of data with anchors (&) and aliases (*). Some DevOps tools support this; others don’t, so check the tool’s docs.
Example:
defaults: &default-env
ENVIRONMENT: production
DEBUG: "false"
staging:
environment:
<<: *default-env # merge defaults into this map
ENVIRONMENT: staging # override a field
production:
environment:
<<: *default-envKey ideas:
&default-envdefines an anchor.*default-envreferences it.<<:is a merge key (supported in many YAML parsers but not all tools).
Simpler alias:
base-image: &base "ubuntu:22.04"
services:
web:
image: *base
worker:
image: *baseCommon Pitfalls in DevOps YAML
1. Mixing tabs and spaces
Most tools will reject tabs:
- Configure your editor to “insert spaces for tab”.
- If something breaks “for no reason,” check for tabs.
2. Misaligned indentation
Bad:
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Build # wrong indentation
run: makeGood:
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Build
run: make3. Special characters and quoting
Characters like :, #, {, }, [, ], ,, &, *, ?, % can cause parsing issues.
If a string contains colons or starts with {/[ or looks like a boolean/number, prefer quotes:
url: "https://example.com:443/path"
version: "1.0.0-beta"
password: "abc:123#456"4. Duplicate keys
YAML technically allows duplicate keys in a map; usually the last one wins, which is confusing:
env:
DEBUG: "true"
DEBUG: "false" # this one wins; you might not noticeAvoid duplicates; some linters can warn about this.
5. File extensions and encodings
- Use
.ymlor.yaml(both are common; some tools prefer one). - Use UTF‑8 encoding.
- Don’t mix YAML with tabs or binary content.
Validating and Testing YAML
Before pushing or applying DevOps configs, validate YAML syntax:
- Use a CLI tool:
yamllint,yq, or the tool’s built-in validation (e.g.kubectl apply --dry-run=client -f file.yaml). - Many IDEs/ editors have YAML syntax checking and indentation guides.
Example with yamllint (on many Linux distros):
yamllint your-file.yamlThis helps catch indentation, type, and formatting issues early.
Putting It Together: A Small DevOps Example
A compact example combining key YAML features you’ll see in practice:
pipeline:
name: build-and-test
on:
push:
branches: [main, develop]
env: &default-env
ENVIRONMENT: ci
DEBUG: "false"
jobs:
build:
runs-on: ubuntu-latest
env:
<<: *default-env
DEBUG: "true"
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y make
- name: Run tests
run: make testAs you work with specific DevOps tools later in the course, they’ll each add their own keys and structure on top of these same YAML basics. The syntax rules here stay the same across tools.