YAML Basics¶
A quick reference for YAML syntax used throughout Kubernetes manifests.
What is YAML?¶
YAML (YAML Ain't Markup Language) is a human-readable data serialization format commonly used for configuration files. Kubernetes uses YAML to define resources.
Basic Syntax¶
Key-Value Pairs¶
Nested Objects (Indentation Matters!)¶
Important: YAML uses spaces for indentation, NOT tabs. Standard is 2 spaces.
Lists (Arrays)¶
# Method 1: Dash notation
ports:
- 80
- 443
- 8080
# Method 2: Inline (JSON-style)
ports: [80, 443, 8080]
Lists of Objects¶
containers:
- name: nginx
image: nginx:latest
ports:
- containerPort: 80
- name: sidecar
image: busybox:latest
command: ["sleep", "3600"]
Common Patterns in Kubernetes¶
Complete Pod Example¶
apiVersion: v1 # API version
kind: Pod # Resource type
metadata: # Metadata section
name: my-pod
labels:
app: web
spec: # Specification section
containers:
- name: nginx
image: nginx:1.21
ports:
- containerPort: 80
Multi-Document YAML¶
Use --- to separate multiple resources in one file:
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
data:
key: value
---
apiVersion: v1
kind: Service
metadata:
name: app-service
spec:
selector:
app: web
ports:
- port: 80
Data Types¶
Strings¶
# Unquoted (most common)
name: my-app
# Quoted (use when string contains special characters)
name: "my-app: production"
name: 'special:characters'
# Multi-line strings
description: |
This is a multi-line string.
Each line is preserved.
Including newlines.
# Folded multi-line (newlines become spaces)
description: >
This is also multi-line
but will be folded into
a single line with spaces.
Numbers¶
age: 30 # Integer
price: 29.99 # Float
port: 8080 # Integer
memory: "512Mi" # String (Kubernetes resource format)
Booleans¶
# These are all valid boolean true:
enabled: true
enabled: True
enabled: TRUE
enabled: yes
# These are all valid boolean false:
enabled: false
enabled: False
enabled: FALSE
enabled: no
Special Characters¶
Comments¶
Null Values¶
Anchors and Aliases (Reusing Values)¶
# Define an anchor with &
defaults: &default-labels
env: production
team: platform
# Reference it with *
service1:
labels:
<<: *default-labels # Merge
app: web
service2:
labels:
<<: *default-labels
app: api
# Results in:
# service1.labels = {env: production, team: platform, app: web}
# service2.labels = {env: production, team: platform, app: api}
Common Mistakes¶
1. Tabs vs Spaces¶
# WRONG - uses tabs (invisible here)
metadata:
name: my-app
# CORRECT - uses spaces
metadata:
name: my-app
2. Incorrect Indentation¶
# WRONG - inconsistent indentation
metadata:
name: my-app
labels:
app: web
# CORRECT - consistent 2-space indentation
metadata:
name: my-app
labels:
app: web
3. List Item Indentation¶
# WRONG - list items not aligned
containers:
- name: nginx
image: nginx
- name: redis
image: redis
# CORRECT - list items aligned
containers:
- name: nginx
image: nginx
- name: redis
image: redis
4. Mixing Formats¶
# WRONG - inconsistent list format
containers:
- name: nginx
- image: nginx
name: redis # Properties should be grouped
# CORRECT
containers:
- name: nginx
image: nginx
- name: redis
image: redis
5. Quotes Around Numbers¶
# Be careful with numbers in strings
port: "8080" # This is a STRING
port: 8080 # This is a NUMBER
# In Kubernetes, resource values are strings:
memory: "512Mi" # CORRECT
cpu: "0.5" # CORRECT
replicas: 3 # CORRECT (integer)
Validation Tools¶
kubectl (Kubernetes)¶
# Validate syntax (doesn't create resources)
kubectl apply -f myfile.yaml --dry-run=client
# Validate against the cluster
kubectl apply -f myfile.yaml --dry-run=server
Online Validators¶
Editor Support¶
Most modern editors support YAML:
- VS Code: YAML extension by Red Hat
- vim: Built-in syntax highlighting
- IntelliJ: Built-in support
Kubernetes-Specific Conventions¶
Required Fields (Most Resources)¶
apiVersion: v1 # Required
kind: Pod # Required
metadata: # Required
name: my-pod # Required
spec: # Required (for most resources)
# ... resource-specific fields
Label Naming Conventions¶
metadata:
labels:
# Recommended format: domain/name
app.kubernetes.io/name: myapp
app.kubernetes.io/instance: myapp-production
app.kubernetes.io/version: "1.0"
app.kubernetes.io/component: frontend
app.kubernetes.io/part-of: myproject
# Simple format (also valid)
app: myapp
tier: frontend
environment: production
Resource Naming Rules¶
- Lowercase alphanumeric characters,
-, or. - Must start and end with alphanumeric character
- Max 253 characters (for most resources)
# VALID names
my-app
my.app
my-app-123
web-frontend
# INVALID names
My-App # uppercase not allowed
my_app # underscores not allowed
-myapp # can't start with dash
myapp- # can't end with dash
Practice Exercise¶
Try to spot the errors in this YAML:
apiVersion: v1
kind: pod
metadata:
Name: my-pod
labels:
app: web
spec:
containers:
- name: nginx
image: nginx
ports:
- containerport: 80
Click to see the corrections
apiVersion: v1
kind: Pod # Should be capitalized
metadata:
name: my-pod # Should be lowercase 'name'
labels:
app: web # Needs proper indentation
spec:
containers:
- name: nginx # Proper list indentation
image: nginx # Same level as 'name'
ports:
- containerPort: 80 # Proper camelCase
Errors:
kind: pod→ should bePod(capitalized)Name:→ should bename:(lowercase)app: web→ incorrect indentation under labelscontainerslist items → inconsistent indentationcontainerport→ should becontainerPort(camelCase)
Additional Resources¶
Pro Tip: Use kubectl explain to see the structure of any Kubernetes resource: