A health endpoint is not useful merely because it returns HTTP 200. Kubernetes probes drive different actions, and using the same deep dependency check for every probe can turn a small outage into a restart storm.

Good probe design starts with semantics: readiness controls traffic, liveness decides whether a container should restart, and startup protects slow initialization. This guide shows how to choose checks, thresholds and protocols that support recovery without hiding failure.

What you will learn

  • Readiness removes an unready Pod from normal Service traffic without restarting it.
  • Liveness should detect a locally unrecoverable state, not every dependency failure.
  • Startup delays liveness and readiness until slow initialization completes.
  • Timeouts, frequency and thresholds must match real latency and recovery behavior.

Readiness is a traffic decision

A readiness probe asks whether this Pod can serve requests now. When it fails, the Pod becomes unready and is normally removed from Service endpoints. The process remains running and can recover without restart disruption.

Readiness may verify local initialization and capacity. Be careful with shared dependencies: if every Pod becomes unready during one downstream outage, the upstream service can disappear even when it could return a controlled error.

Liveness is a restart decision

A liveness failure eventually causes the kubelet to restart the container. This is appropriate for a deadlock or a process that cannot recover internally. It is dangerous for overload because restarts add cold starts and pressure.

Keep liveness local and inexpensive. If restarting cannot repair the reported condition, it probably does not belong in liveness. Monitor dependencies separately and design explicit fallback behavior.

Startup protects slow applications

Until startup succeeds, Kubernetes does not execute liveness or readiness. This gives migrations, cache warming and large runtimes time to initialize while preserving responsive normal liveness thresholds.

The maximum startup window is failureThreshold multiplied by periodSeconds. Cover a realistic worst case, then investigate initialization when normal startup approaches that limit.

A balanced HTTP configuration

Use dedicated paths and make handlers cheap with strict internal timeouts. The example allows five minutes for startup and checks readiness more frequently than liveness. Adapt values from measurements.

HTTP, TCP, command and gRPC probes have different trade-offs. Choose the simplest protocol that accurately represents the intended decision.

startupProbe:
  httpGet: {path: /health/startup, port: health}
  periodSeconds: 5
  failureThreshold: 60
readinessProbe:
  httpGet: {path: /health/ready, port: health}
  periodSeconds: 5
  timeoutSeconds: 2
livenessProbe:
  httpGet: {path: /health/live, port: health}
  periodSeconds: 10
  timeoutSeconds: 2

Rollouts and graceful termination

Readiness determines when new Pods count as available. Combine it with sufficient rollout capacity and minReadySeconds when a Pod must remain stable before progression. A probe that succeeds too early shifts traffic before caches or connections are ready.

On shutdown, stop accepting new work and allow in-flight requests to finish within terminationGracePeriodSeconds. Test application shutdown, endpoint propagation and load-balancer behavior together.

Debug probe failures

Use kubectl describe pod to read events, then reproduce the request from the correct network context. Confirm scheme, path, named port, response time and status code. Review current and previous logs when liveness restarts containers.

Graph failures with restarts, latency, throttling, memory pressure and deployments. A wave across replicas often indicates a shared dependency; one replica suggests node networking, local state or process failure.

Production checklist

  • Give startup, readiness and liveness distinct semantics.
  • Keep liveness independent of dependencies a restart cannot repair.
  • Set explicit timeouts and test under CPU pressure.
  • Use startup probes for variable initialization.
  • Test rollouts and graceful termination with traffic.
  • Alert on probe failures and correlate with revisions.

Frequently asked questions

Can readiness and liveness share an endpoint?

They can, but it is risky because the decisions differ. Temporary conditions may justify removing traffic without restarting.

Does startupProbe run forever?

No. It succeeds once and hands control to readiness and liveness, or eventually fails and triggers restart behavior.

Why do probes fail only under load?

The handler may compete for CPU, threads or connections. Check saturation, keep it cheap and choose timeouts from measurements.

Continue learning Kubernetes

Official Kubernetes references