YAML editing patterns

Indentation rules

YAML uses spaces for indentation — tabs are a syntax error. The convention in Kubernetes manifests is 2 spaces per level.

# Correct — 2-space indent
spec:
  containers:
    - name: web
      image: nginx:1.27

# Wrong — tab character (invisible, but YAML parsers reject it)
spec:
  containers:

Strings and quoting

YAML auto-types unquoted values. This causes surprises:

Value	YAML interprets as
`true`, `false`	Boolean
`1.0`	Float
`1`	Integer
`on`, `off`, `yes`, `no`	Boolean (YAML 1.1)
`null`, `~`	Null

When in doubt, quote it:

env:
  - name: FEATURE_FLAG
    value: "true"       # string, not boolean
  - name: VERSION
    value: "1.0"        # string, not float

Multi-line strings

YAML has two block scalar styles for multi-line content:

Literal block (`|`) — preserves newlines

data:
  config.ini: |
    [server]
    port=8080
    debug=false

Folded block (`>`) — joins lines with spaces

metadata:
  annotations:
    description: >
      This is a long description
      that gets folded into a single
      line with spaces.

The - suffix strips the trailing newline: |- and >-.

Multi-document files

A single YAML file can contain multiple documents separated by ---:

apiVersion: v1
kind: Service
metadata:
  name: my-app
spec:
  selector:
    app: my-app
  ports:
    - port: 80
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
        - name: web
          image: my-registry/my-app:1.0

kubectl apply -f handles multi-document files natively.

Anchors and aliases

Anchors (&) and aliases (*) let you reuse values without duplication:

common_labels: &labels
  app: my-app
  team: platform

deployment:
  metadata:
    labels:
      <<: *labels
  spec:
    template:
      metadata:
        labels:
          <<: *labels

Labels and selectors pattern

Every Kubernetes manifest needs labels that match its selectors. A common minimal set:

metadata:
  labels:
    app.kubernetes.io/name: my-app
    app.kubernetes.io/version: "1.0"
    app.kubernetes.io/managed-by: argocd

The app.kubernetes.io/* labels are the recommended convention. At minimum, use app.kubernetes.io/name so Services and monitoring can select your Pods consistently.

Resource requests and limits

Always declare resource requests and limits — on Kestrel, quota is enforced against a shared resource pool across all of your tenant’s namespaces, not per individual namespace:

containers:
  - name: web
    resources:
      requests:
        cpu: 100m
        memory: 128Mi
      limits:
        cpu: 500m
        memory: 256Mi

Field	Meaning
`requests`	Guaranteed minimum — used for scheduling
`limits`	Hard ceiling — container is throttled (CPU) or killed (memory) if exceeded

Common gotchas

Forgetting matchLabels — a Deployment’s spec.selector.matchLabels must match the Pod template’s metadata.labels. If they don’t match, the Deployment can’t find its Pods.
Port mismatch — the Service targetPort must match the container’s containerPort. A mismatch means traffic reaches the Pod but hits a closed port.
Image tag latest — never use latest in production manifests. It’s mutable, so you can’t tell which version is running and rollbacks don’t work.
Trailing whitespace in values — value: "my-secret " includes the space. Use |- for block scalars or quote carefully.

Editor setup

For VS Code or similar editors, install a YAML language server extension with Kubernetes schema support. Recommended settings:

{
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.renderWhitespace": "boundary",
  "files.trimTrailingWhitespace": true
}

Next steps

Containers 101 — review container and image fundamentals
Core Kubernetes objects — how these manifests map to running resources