YAML Manifests

Anatomy of a Manifest

Every accepted object carries four top-level keys:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: prod
  labels: { app: web }
spec:
  replicas: 3

apiVersion names the group/version that serves the kind; metadata.name plus namespace must be unique per kind. Labels drive selection — ReplicaSets and Services match pods on them — while annotations hold non-identifying metadata such as commit SHAs. Everything else sits under spec, and its shape is fixed by that apiVersion's schema: apps/v1 rejects a Deployment whose spec.selector does not match template labels.

Separate multiple documents in one file with ---.

Apply, Validate, Diff

Iterate safely before touching a live object:

kubectl apply -f web.yaml --dry-run=client   # parse locally
kubectl apply -f web.yaml --dry-run=server   # ask the API server
kubectl diff -f web.yaml                     # preview the change
kubectl apply -f web.yaml
kubectl apply -k overlays/staging/           # kustomize overlay

Apply records a last-applied-configuration annotation, which powers three-way merge on later applies. Fields you never declared are filled by defaulting — imagePullPolicy, terminationGracePeriodSeconds: 30 — and appear in kubectl get -o yaml alongside managedFields showing which actor last wrote each field.

Bootstrap a starting template with kubectl create deploy web --image=nginx --dry-run=client -o yaml > web.yaml.

Manifest Pitfalls

Pitfall 1 — YAML coercion. Two-space indentation is the convention; a tab fails parsing before the API sees it. Quote values that could parse otherwise: cpu: "1" keeps the string form, and "on" or "no" stops becoming booleans.

Pitfall 2 — fighting controllers over fields. Owners like the ReplicaSet controller write status and selectors; hand edits are overwritten on the next reconcile. On apply, remember three-way merge only removes keys your previous config contained — a field you never declared stays untouched.

Interview-ready: list the required keys, contrast labels (selection, must match selectors) with annotations (metadata only), and describe your pipeline — client dry-run, server dry-run, diff, apply — with Git as the audit trail.