Back to updates

Add startup probe guidance to Kubernetes deployment docs

Pending review
by Sarah KimAug 31, 2026
New page154 words · 4 sections

Startup Probes

If pods enter CrashLoopBackOff after deployment, the liveness probe may be failing before the application finishes starting.

Symptoms

  • Pods cycle between Running and CrashLoopBackOff
  • kubectl describe pod shows: "Liveness probe failed: HTTP probe failed with statuscode: 503"
  • The app takes longer to start than the liveness probe's initialDelaySeconds

Solution

Add a startupProbe to your deployment spec:

startupProbe:
  httpGet:
    path: /healthz
    port: 8080
  failureThreshold: 30
  periodSeconds: 10

This allows up to 5 minutes for startup (30 failures × 10s interval). Once the startup probe succeeds, Kubernetes switches to the regular liveness probe.

When to use startupProbe vs initialDelaySeconds

  • startupProbe: Preferred for apps with variable startup times. Kubernetes will not run liveness/readiness checks until the startup probe succeeds.
  • initialDelaySeconds: Use when startup time is predictable and consistent. Simpler but less flexible — if startup takes longer than expected, the pod will be killed.