Kubernetes engineers are often jokingly called “YAML Engineers”, and it is not completely unfair. Most operational changes arrive as YAML: Deployments, Services, ConfigMaps, RBAC rules, Helm values, GitOps pull requests. The format looks simple until one space, quote, or implicit type changes what the API server receives.

What YAML Actually Is

YAML (YAML Ain’t Markup Language) is a human-readable data serialization standard. It’s a superset of JSON, meaning every valid JSON file is also a valid YAML file.

Common Pitfalls

1. Indentation Drift

YAML relies on indentation (spaces, never tabs) to define structure. A single wrong space can move a field to the wrong parent or make the manifest invalid.

# BAD
spec:
  containers:
  - name: nginx
   image: nginx # Wrong indentation!

2. The “No” Problem

In older YAML parsers, no was interpreted as false.

# Potentially ambiguous
enableFeature: no

# Safe
enableFeature: "no"

3. Numbers vs Strings

Port numbers and versions can be tricky.

# BAD
version: 1.10 # Parsed as number 1.1 (floating point)

# GOOD
version: "1.10" # Parsed as string "1.10"

Multi-Document Files

You can put multiple Kubernetes resources in a single file by separating them with ---.

apiVersion: v1
kind: Service
metadata:
  name: my-service
spec:
  ports:
  - port: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  replicas: 3

Tools That Save Time

Do not rely on visual inspection alone. Use tooling before a bad manifest reaches the cluster.

1. VS Code Extensions

Install the official Kubernetes extension by Microsoft. It provides:

  • IntelliSense (auto-completion)
  • Validation against schemas
  • Hover documentation

2. Kubeval / Kubeconform

Validate your YAML against the official Kubernetes schemas before you apply it.

kubeconform deployment.yaml

3. YQ

yq is like jq but for YAML. It’s great for scripting edits.

# Change image tag
yq e '.spec.template.spec.containers[0].image = "nginx:latest"' -i deployment.yaml

What to Remember

YAML is easy to start writing and easy to misread.

  • Always quote strings that look like numbers or booleans.
  • Use 2 spaces for indentation.
  • Use a linter or validator.