Pod Lifecycle

Lifecycle State Machine

Key Numbers

Pod Spec with Every Lifecycle Knob

apiVersion: v1
kind: Pod
metadata:
  name: web
spec:
  terminationGracePeriodSeconds: 60

  initContainers:
    - name: wait-for-db
      image: busybox
      command: [sh, -c, "until nc -z db 5432; do sleep 1; done"]

    - name: envoy             # 1.29+ native sidecar
      image: envoyproxy/envoy
      restartPolicy: Always   # makes it a sidecar (started in init order, runs alongside main)
      lifecycle:
        preStop:
          exec:
            command: [sh, -c, "curl -X POST localhost:9090/healthcheck/fail; sleep 25"]

  containers:
    - name: app
      image: myapp:1.0
      ports: [ { containerPort: 8080 } ]

      startupProbe:
        httpGet: { path: /healthz, port: 8080 }
        failureThreshold: 30      # 30 * 10s = 5 min to start
        periodSeconds: 10

      readinessProbe:
        httpGet: { path: /ready, port: 8080 }
        periodSeconds: 5
        failureThreshold: 3       # 15s before traffic stops

      livenessProbe:
        httpGet: { path: /alive, port: 8080 }
        periodSeconds: 10
        failureThreshold: 3       # 30s before container restart

      lifecycle:
        preStop:
          exec:
            command: [sh, -c, "sleep 5 && kill -SIGTERM 1"]
            # gives Service controller time to remove from endpoints

      resources:
        requests: { cpu: 100m, memory: 128Mi }
        limits:   { cpu: 500m, memory: 512Mi }

Init Containers vs Sidecars

# Init container — runs to completion, in order, BEFORE main containers
# Use for: schema migrations, fetching configs, waiting for dependencies

# Sidecar (1.29+ native) — initContainer with restartPolicy: Always
# Use for: service mesh proxy (Istio envoy), log shipper (Fluent Bit),
#          metrics scraper, secret rotator
#
# Critical difference vs old "just put it as a regular container":
# - Starts BEFORE main containers (in init order)
# - Restarts independently if it crashes
# - Receives SIGTERM ONLY AFTER all main containers have exited
# - Lets the proxy drain after the app is gone — finally fixes Istio's
#   "envoy died before app drained connections" race

Probes: HTTP, TCP, exec, gRPC

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
    httpHeaders:
      - name: X-Health-Check, value: kubelet
  initialDelaySeconds: 5
  periodSeconds: 5
  timeoutSeconds: 2
  successThreshold: 1
  failureThreshold: 3

# TCP probe (just opens a socket)
livenessProbe:
  tcpSocket: { port: 5432 }

# exec probe (any command exit-zero is success)
livenessProbe:
  exec:
    command: [pg_isready, -h, localhost]

# gRPC probe (1.27+)
readinessProbe:
  grpc:
    port: 9000
    service: my.health.v1.HealthService

Graceful Shutdown

# Timeline of a deletion:
T=0:   API server marks Pod for deletion (deletionTimestamp set)
T=0:   Endpoints controller removes Pod from Service (kube-proxy/eBPF updates rules)
T=0:   kubelet runs preStop hooks
T=preStop_done: kubelet sends SIGTERM to main process (PID 1)
T=preStop_done + grace_period: kubelet sends SIGKILL if still alive

# Common pattern for HTTP servers:
lifecycle:
  preStop:
    exec:
      command: [sh, -c, "sleep 10"]   # let endpoints propagate
# Then SIGTERM → app drains in-flight requests → exits.

# Apps that don't handle SIGTERM end up SIGKILL'd at the grace period.
# Java's System.exit(0) handlers, Go's signal.Notify, Node's process.on('SIGTERM')

PodDisruptionBudget and Topology Spread

# PDB — at most 1 pod down at a time (or expressed as %)
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata: { name: api }
spec:
  minAvailable: 2
  selector: { matchLabels: { app: api } }

# OR
spec:
  maxUnavailable: 1
  selector: { matchLabels: { app: api } }

# Topology Spread — spread across zones AND across nodes
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: DoNotSchedule
          labelSelector: { matchLabels: { app: api } }
        - maxSkew: 1
          topologyKey: kubernetes.io/hostname
          whenUnsatisfiable: ScheduleAnyway
          labelSelector: { matchLabels: { app: api } }

Tradeoffs

Frequently Asked Questions