Kubernetes Deployment YAML

Nginx Deployment example

A complete, working Deployment that runs three Nginx replicas with sensible CPU and memory bounds:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 256Mi

Field-by-field:

• apiVersion: apps/v1 - the API group and version for Deployments.
• kind: Deployment - the resource type.
• metadata.name - unique within the namespace.
• spec.replicas: 3 - desired pod count.
• spec.selector.matchLabels - must match the labels in spec.template.metadata.labels, or the Deployment will not own its pods.
• spec.template - the pod template, used to create each replica.
• resources.requests / limits - what the scheduler reserves and the maximum the container can consume.

Service manifest

A Deployment without a Service is unreachable from anywhere except the pod itself. The matching ClusterIP Service routes traffic to any pod with the app: nginx label:

apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  type: ClusterIP
  selector:
    app: nginx
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80

port is what other workloads in the cluster call. targetPort is the pod port traffic is forwarded to. Use type: NodePort or LoadBalancer to expose the service outside the cluster.

ConfigMap example

A ConfigMap stores non-secret configuration as key-value pairs, with optional embedded YAML or JSON files:

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  LOG_LEVEL: info
  FEATURE_FLAGS: "search,recommendations"
  config.yaml: |
    server:
      port: 8080
      timeout: 30s

The config.yaml entry uses a literal block scalar (|) to embed a multiline value. See the multiline strings guide for the full block-scalar reference.

Secret example

stringData takes plaintext that Kubernetes base64-encodes when it stores the Secret. Use this form rather than data (which expects values to already be base64) to keep the YAML readable:

apiVersion: v1
kind: Secret
metadata:
  name: app-secrets
type: Opaque
stringData:
  DATABASE_URL: "postgres://user:pass@db:5432/app"
  API_KEY: "sk_live_xxxxxxxxxxxxx"

Do not commit raw Secret manifests to Git - base64 is encoding, not encryption. Use Sealed Secrets, External Secrets Operator, or SOPS to handle them safely.

Probes and environment injection

Production-grade Deployments wire env vars from a ConfigMap and Secret, and expose readiness and liveness probes so Kubernetes can stop sending traffic to broken pods:

# Same Deployment with health probes and env from ConfigMap + Secret
spec:
  template:
    spec:
      containers:
        - name: api
          image: myorg/api:1.4.2
          ports:
            - containerPort: 8080
          envFrom:
            - configMapRef:
                name: app-config
            - secretRef:
                name: app-secrets
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 15
            periodSeconds: 20

readinessProbe controls when traffic is routed to the pod. livenessProbe controls when the kubelet restarts the pod. Set both - they answer different questions.

Multiple resources in one file

YAML supports multiple documents in a single file separated by ---. This is how a single manifest ships a Namespace, Deployment, Service, and ConfigMap together:

# Multiple resources in one file - separated by ---
apiVersion: v1
kind: Namespace
metadata:
  name: production
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: production
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.27

Applying with kubectl

• kubectl apply -f file.yaml - create or update from a single file.
• kubectl apply -f . - apply every YAML in the directory.
• kubectl apply --dry-run=client -f file.yaml - validate without contacting the cluster.
• kubectl diff -f file.yaml - preview the change that apply would make.
• kubectl rollout status deployment/<name> - wait for the new replicas to become healthy.
• kubectl rollout undo deployment/<name> - roll back to the previous revision.

Common errors

• error validating data: unknown field "X" - typo in a field name, or wrong API version. Check the apiVersion first.
• spec.selector: required value - Deployments require spec.selector.matchLabels matching the pod template's labels.
• found character that cannot start any token - tabs in indentation. YAML rejects tabs; use two spaces. Run the file through the YAML validator to find the exact line.
• ImagePullBackOff - not a YAML problem; check the image name, tag, and pull secret.
• CrashLoopBackOff - container starts and exits. Inspect logs with kubectl logs <pod> and check the readiness probe.

Validate and convert

Indentation bugs in Kubernetes YAML are silent until apply time. Drop your manifest into the YAML validator before running kubectl, or use the YAML formatter to normalize indentation across a repo. For shared blocks across multiple manifests, see YAML anchors and merge keys.