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:

Caution

Most YAML parse errors on Kestrel trace back to a stray tab or inconsistent indent width. Configure your editor to insert spaces and show whitespace characters.

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.

Note

On Kestrel, prefer committing manifests to a repo and letting ArgoCD apply them rather than running kubectl apply directly — ArgoCD self-heal reverts manual changes. See Bring your own repo.

Anchors and aliases

Anchors (&) and aliases (*) let you reuse values without duplication. In a Kubernetes manifest, the anchor must ride on a real field at its first occurrence — a made-up top-level key like common_labels: is an unknown field the API server rejects:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels: &labels
    app: my-app
    team: platform
spec:
  replicas: 2
  selector:
    matchLabels: *labels
  template:
    metadata:
      labels: *labels
    spec:
      containers:
        - name: web
          image: my-registry/my-app:1.0

Note

Anchors work within a single YAML document. They don’t span across --- boundaries or across files.

Labels and selectors pattern

Workload controllers (Deployments, ReplicaSets) and Services find their Pods via label selectors, so the Pod template’s labels must match — and labelling every resource consistently makes selection and monitoring easier. 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

1. 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.

2. Port mismatch — the Service targetPort must match the container’s containerPort. A mismatch means traffic reaches the Pod but hits a closed port.

3. 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.

4. Trailing whitespace in values — value: "my-secret " includes the space; quoting preserves it. The fix is to delete the stray space inside the quotes. The editor settings below (renderWhitespace, files.trimTrailingWhitespace) help you spot and strip trailing whitespace before it ships.

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