Kubernetes YAML: Common Mistakes and How to Avoid Them

Kubernetes config is YAML, which means it inherits all of YAML's footguns plus a few of its own. These are the mistakes that cause the most kubectl apply headaches.

1. Indentation under lists

Items in a list need consistent indentation, and the keys under each item must align:

containers:
  - name: app
    image: nginx
   ports:        # misaligned, breaks the manifest
      - containerPort: 80

Fix: ports must align with name and image under the same list item.

2. Numbers that should be strings

Kubernetes often wants values as strings even when they look numeric — image tags and version labels especially:

metadata:
  labels:
    version: 1.0      # becomes the float 1, label fails

Fix: Quote it: version: "1.0".

3. The string-boolean trap

A label value of true becomes a boolean, but label values must be strings:

  labels:
    enabled: true    # boolean, but labels must be strings

Fix: enabled: "true".

4. Tabs anywhere

YAML forbids tabs. A single tab from an editor or paste fails the whole manifest with a cryptic error. Configure your editor to insert spaces.

5. Wrong apiVersion or kind casing

These are case-sensitive. Deployment works; deployment does not.

6. Multi-document files

A single file can hold multiple manifests separated by ---. Forgetting the separator merges them into one invalid document:

apiVersion: v1
kind: Service
---
apiVersion: apps/v1
kind: Deployment

Catch errors before applying

kubectl apply --dry-run=client catches schema issues, but pure YAML syntax errors fail earlier and more cryptically. Paste your manifest into the validator first — it pinpoints indentation, tab, and quoting problems in plain English. Use the visualizer to confirm the structure matches your intent.