Configure each Kubernetes probe for the action its failure triggers. Startup answers whether initialization has completed. Readiness answers whether this pod should receive new traffic now. Liveness answers whether restarting the container is likely to recover it. Reusing one deep dependency check for all three turns a downstream outage into a restart storm.
Start with the control-plane consequence
A failed readiness probe removes a pod from matching Service endpoints while the container keeps running. That is appropriate for temporary inability to serve, such as a drained connection pool or local cache warmup. A failed liveness probe causes the kubelet to restart the container after its threshold. Use it only for states where the process cannot make progress and a restart is a plausible repair.
The Kubernetes probe concepts documentation distinguishes these semantics and explains that a startup probe disables liveness and readiness checks until it succeeds. This gives slow applications a bounded initialization window without weakening liveness detection for the rest of their lifetime.
A startup endpoint should succeed only after one-time initialization needed to serve has completed. Size failureThreshold × periodSeconds above the observed worst-case startup time plus margin. If it expires, Kubernetes restarts the container, so an initialization step must tolerate interruption and retry. Avoid hiding an unbounded migration behind a very large threshold; database migrations should have separate ownership and progress.
Keep liveness shallow and local
Good liveness checks detect a wedged event loop, unrecoverable internal deadlock, or corrupted local state. They should be cheap, deterministic, and independent of optional downstreams. If the database is unavailable, restarting every API pod consumes more connections and erases diagnostic state while the database remains unavailable. Let the API stay alive, become unready if it truly cannot serve, and expose dependency health in metrics.
Do not make liveness depend on the same saturated worker pool it is intended to diagnose unless you have reserved probe capacity. During load, a queued probe can time out even though the process is working. Conversely, a health thread that always answers can conceal a dead request path. Test the exact failure you expect it to catch.
Make readiness represent usable traffic
Readiness may include critical local and downstream conditions, but only when removing this pod improves the situation. A pod with a broken per-instance credential should be unready. A shared database outage affects every replica; marking all unready may make the load balancer return immediate errors instead of a controlled degraded response. Decide which behavior serves users and recovery best.
The official probe configuration task documents HTTP, TCP, gRPC, and command probes along with timing and threshold fields. Choose the protocol closest to the serving path. Set timeouts from measured local behavior, not from the end-user request timeout. Use success and failure thresholds to resist single-sample noise without delaying removal dangerously.
Readiness gates rollout progress, so a new release whose probe checks an unavailable optional feature can stall deployment. During termination, stop accepting new work before the process exits and coordinate readiness with graceful shutdown. Long-lived connections may require application-specific draining because endpoint removal does not recall requests already in flight.
Exercise failures before production
Test slow startup, a wedged handler, exhausted local connections, a shared database outage, DNS failure, CPU throttling, and graceful termination. Observe endpoint membership, restart count, termination reason, and user-facing errors. Confirm probe handlers have strict resource bounds and do not leak secrets in responses.
The next step is to write one sentence for each probe: “When this fails, Kubernetes should take this action because it repairs or isolates this state.” If the sentence is false, change the probe. Review by 2026-12-05 or after a runtime or Kubernetes upgrade.
Sources are linked throughout this guide. Product capabilities can change; consult the linked documentation for your deployment.
Read our editorial approach ↗