Kubernetes Probes: Liveness, Readiness, and Startup Probe Configuration
Readiness removes traffic, liveness restarts the container, startup buys time for slow boots. Why a liveness probe on the database restarts every replica, and the timeout default that causes random restarts.

Quick Summary
Kubernetes has three probes and they answer three different questions. The readiness probe asks "should this pod receive traffic right now?" — failing it removes the pod from the Service's endpoints without restarting anything. The liveness probe asks "is this container still alive in a useful sense?" — failing it makes the kubelet kill and restart the container. The startup probe asks "has this container finished starting?" — until it succeeds, liveness and readiness are not evaluated at all, which is exactly what a slow-starting JVM or a large cache warm-up needs.
The timing fields decide everything about how a probe behaves: periodSeconds (default 10) is the check interval, timeoutSeconds (default 1) is the per-check limit, failureThreshold (default 3) is how many consecutive failures count as a failure, and successThreshold (default 1) is how many consecutive successes it takes to recover (and must be 1 for liveness and startup). A startup probe's tolerance is failureThreshold × periodSeconds, so failureThreshold: 30 with periodSeconds: 5 gives an app 150 seconds to come up before the container is killed for failing to start.
The single most common design error is pointing liveness at an endpoint that depends on a database: a short database blip then restarts every replica at once. This guide covers the handler types and their success conditions, correct timing, the separation between liveness and readiness, gRPC probes, and the failure messages that tell you which probe fired.
Basic Syntax & Core Signatures
containers:
- name: api
image: ghcr.io/acme/api:1.4.2
ports: [{ name: http, containerPort: 8080 }]
startupProbe:
httpGet: { path: /healthz, port: http }
periodSeconds: 5
failureThreshold: 30 # up to 150s to start
livenessProbe:
httpGet: { path: /healthz, port: http }
periodSeconds: 10
timeoutSeconds: 2
failureThreshold: 3 # restart after ~30s of failures
readinessProbe:
httpGet: { path: /readyz, port: http }
periodSeconds: 5
timeoutSeconds: 2
successThreshold: 1
failureThreshold: 3 # out of endpoints after ~15s# Handlers
readinessProbe:
tcpSocket: { port: 5432 } # connection succeeds
livenessProbe:
exec: { command: ["/bin/sh", "-c", "test -f /tmp/healthy"] } # exit 0
readinessProbe:
httpGet:
path: /health
port: 8443
scheme: HTTPS # 200-399 is success
httpHeaders: [{ name: Host, value: internal.example.com }]
startupProbe:
grpc: { port: 9090, service: "grpc.health.v1.Health" } # SERVINGkubectl get pods -o wide # READY 1/1, 0/1
kubectl describe pod api-1 | grep -iE 'Liveness|Readiness|Startup|Unhealthy'
kubectl get pod api-1 -o jsonpath='{.status.containerStatuses[0].ready}{"\n"}'
kubectl get pod api-1 -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}{"\n"}'
kubectl get endpointslices -l kubernetes.io/service-name=api # who receives traffic| Field | Default | Applies to |
|---|---|---|
initialDelaySeconds | 0 | All probes (unnecessary with a startup probe) |
periodSeconds | 10 | All probes |
timeoutSeconds | 1 | All probes |
successThreshold | 1 | Readiness may be > 1; must be 1 for liveness/startup |
failureThreshold | 3 | All probes |
terminationGracePeriodSeconds | 30 (pod) | Restart after a failed liveness |
Key Comparison Table
| Probe | On failure | On success | Depends on |
|---|---|---|---|
startupProbe | Container killed and restarted | Liveness and readiness begin | App process only |
livenessProbe | Container killed and restarted | Nothing (stays alive) | App process only, never dependencies |
readinessProbe | Pod removed from endpoints | Pod added to endpoints | App plus its dependencies |
| Handler | Success condition | Cost | Notes |
|---|---|---|---|
httpGet | Status 200-399 | One HTTP request | Most common; uses kubelet to pod IP |
tcpSocket | Connection accepted | One TCP handshake | Proves a listener, not that it serves |
exec | Exit code 0 | Forks a process in the container | No shell in distroless images; CPU cost |
grpc | Status SERVING | gRPC health call | Needs the standard health service implemented |
| Symptom | What it means |
|---|---|
Liveness probe failed: HTTP probe failed with statuscode: 503 | App said 503; the endpoint it points at checks something unhealthy |
Readiness probe failed: Get "http://10.244.1.9:8080/readyz": context deadline exceeded | Probe timed out (default 1s) |
Startup probe failed: connection refused | Nothing listening yet on that port |
Readiness probe errored: ... no such host | Probe host resolution failed |
Practical Edge Cases & Deep Dives
1. Liveness that checks the database restarts the whole fleet
livenessProbe:
httpGet: { path: /healthz, port: http } # /healthz pings the database
periodSeconds: 10
failureThreshold: 3A 40-second database failover makes every replica fail liveness at the same moment; the kubelet kills them all, they come back while the database is still down, and the loop repeats. The pod was never unhealthy — it was waiting. Liveness must test only the process's ability to make progress (not deadlocked, event loop responsive, worker threads alive). Dependencies belong in the readiness probe, where failure means "stop sending me traffic" instead of "die".
livenessProbe: { httpGet: { path: /livez, port: http } } # process only
readinessProbe: { httpGet: { path: /readyz, port: http } } # dependencies included2. The 1-second timeout that causes random restarts
timeoutSeconds defaults to 1. A Go or Node service handling a garbage collection pause, or one whose probe endpoint takes a lock, exceeds it occasionally; with failureThreshold: 3 that is three unlucky checks in 30 seconds, which a busy pod will eventually produce. The fix is a cheap probe endpoint plus a timeout that reflects real latency:
livenessProbe:
httpGet: { path: /livez, port: http }
timeoutSeconds: 3
periodSeconds: 10
failureThreshold: 5The opposite mistake is a probe endpoint that performs real work (queries, writes, full health aggregation). With periodSeconds: 5 and dozens of replicas, that is load the application did not need, sometimes more expensive than the traffic the probe protects.
3. A readiness probe that never fails
readinessProbe:
httpGet: { path: /healthz, port: http } # returns 200 as soon as the port opensIf readiness passes before the app can serve — connection pool empty, migrations still running, cache cold — the Deployment reports a successful rollout while clients get 500s. Readiness should include the things that make a request fail: database connectivity, required downstream clients, and any warm-up the app performs. It should not include dependencies that are optional or that would cause permanent removal from the load balancer.
The counterpart: a readiness probe so strict that a transient dependency blip removes every pod at once, which is the same failure as a liveness probe with a low threshold, just gentler.
4. Startup probes for slow starts (and what they replace)
startupProbe:
httpGet: { path: /healthz, port: http }
periodSeconds: 5
failureThreshold: 60 # 300 secondsBefore startup probes, slow starters needed a large initialDelaySeconds on liveness, which delayed detection of a real hang by the same amount for the whole life of the pod. A startup probe gives the container a generous budget once, then liveness runs with a tight threshold. While the startup probe is pending, readiness also does not run, so the pod is not in the endpoints — which is correct.
Note that a failing startup probe restarts the container, and repeated restarts produce CrashLoopBackOff with the startup message in the events, not a liveness message.
5. Probes, ports, and the container that listens on the wrong address
ports: [{ name: http, containerPort: 8080 }]
readinessProbe:
httpGet: { path: /healthz, port: http } # resolves the named portNamed ports keep probes tied to the container's declaration, so a containerPort change does not silently leave a numeric probe pointing at nothing. Two address-level problems recur: an application bound to 127.0.0.1 that the kubelet (probing the pod IP) cannot reach, and a probe against a TLS listener without scheme: HTTPS, which produces a plain-HTTP request the server rejects — visible as a 400 in the app's log and a Readiness probe failed: statuscode: 400 in the pod's events.
kubectl exec deploy/api -- ss -tlnp # 0.0.0.0:8080 vs 127.0.0.1:80806. gRPC, exec, and the probes that cost CPU
readinessProbe:
grpc: { port: 9090 } # requires the standard grpc health service
periodSeconds: 10The grpc handler calls grpc.health.v1.Health/Check and treats SERVING as success; without that service implemented, every probe fails and the pod never becomes ready. For images without a shell (distroless, scratch), exec probes cannot use sh -c or curl; the alternatives are a static health binary baked into the image or an HTTP probe against a port the app exposes.
exec probes fork a process per check, which on a CPU-limited pod competes with the application, and with periodSeconds: 5 across many replicas the cost is measurable. HTTP probes are handled by the kubelet over the pod network and cost the container only the request handling.
Common Runtime & Configuration Mistakes
| Symptom | Cause | Fix |
|---|---|---|
| All replicas restart at once during a dependency outage | Liveness checks a dependency | Move the check to readiness |
| Random restarts under load | 1s timeout, GC pauses | Raise timeoutSeconds/failureThreshold, cheap endpoint |
| Rollout "succeeds" but users see 500s | Readiness passes before the app can serve | Include dependencies and warm-up in readiness |
| Pod ready immediately, traffic too early | initialDelaySeconds 0 with no startup probe | Startup probe, or readiness that reflects state |
CrashLoopBackOff on a slow-starting app | Startup budget too small | Raise failureThreshold × periodSeconds |
connection refused on startup probe | App not listening yet on that port | Verify the port and bind address |
| Probe returns 400 | Probe uses HTTP against a TLS listener | scheme: HTTPS |
exec probe fails on distroless | No shell in the image | HTTP probe or a static binary |
| Probe passes but the pod gets no traffic | Service selector, not the probe | Check endpointslices |
| Pod never becomes ready with a gRPC probe | Health service not implemented | Implement grpc.health.v1 |
| Probe traffic dominates logs | periodSeconds too small | 10-30s is normal |
| Readiness flaps, endpoints churn | Thresholds too tight for normal latency | failureThreshold: 3, successThreshold: 1-2 |
Probes are a contract between the workload and the platform: readiness decides traffic, liveness decides restarts, and startup decides how long the platform should wait before judging either. Set liveness to test only the process, readiness to test what actually serves requests, and a startup probe generous enough for the slowest real boot — and read the event line naming the probe when something fails, because it says which contract was broken.
Try matching browser tools
All toolsSmall utilities that fit Kubernetes work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Kubernetes guides
All Kubernetes guideskubectl Output: jsonpath, custom-columns, and the Debugging Commands Worth Knowing
jsonpath for one value in a script, custom-columns for tables people read, and kubectl debug when the container has no shell. Includes the three quoting layers that break jsonpath.
Kubernetes Namespaces, ResourceQuotas, and LimitRanges
A namespace is only a boundary when quota and limit range make it one. Aggregate caps, per-pod defaults, the admission errors they produce, and namespaces stuck Terminating.
Kubernetes StatefulSets: Ordinal Identities, Headless Services, and PVC Lifecycle
Why each StatefulSet pod keeps a name, a DNS record, and its own PVC; how OrderedReady gates startup on readiness; and how partition-based updates canary a single quorum member.
Kubernetes securityContext, Capabilities, and Pod Security Standards
The five fields that remove most container escapes, which of them only exist at container level, and how the restricted profile enforces the same settings at admission.
More in Kubernetes
All Kubernetes guidesThe guides filed next to this one in Kubernetes, in library order.