Kubernetes Liveness vs Readiness vs Startup Probes: Production YAML and Failure Modes

Kubernetes exposes three probe names that sound similar but drive different actions. A readiness failure should stop regular Service traffic from reaching a Pod. A repeated liveness failure can restart a container. A startup probe gives a slow-starting application time to initialize before the other two probes begin. Confusing those decisions can turn a small dependency slowdown into a restart storm.

Three probes, three operational questions

Readiness runs throughout the container lifecycle. It can fail during overload or maintenance and recover later without a restart. Liveness should detect a condition that a restart can plausibly repair, such as an unrecoverable deadlock. If the process already exits on fatal failure, the container restart policy may be enough without an elaborate liveness check.

A balanced HTTP-probe configuration

ports:
  - name: http
    containerPort: 3000

startupProbe:
  httpGet:
    path: /health/startup
    port: http
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 30

readinessProbe:
  httpGet:
    path: /health/ready
    port: http
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 2

livenessProbe:
  httpGet:
    path: /health/live
    port: http
  periodSeconds: 10
  timeoutSeconds: 2
  failureThreshold: 3
  

This startup budget allows roughly 150 seconds of periodic startup checks, with additional timing nuance from timeouts and scheduling. Measure actual initialization and leave headroom for cold nodes, cache warming, or recovery. Once startup succeeds, the readiness and liveness checks take over.

Named ports make the intent easier to read and reduce duplication if the numeric container port changes. For HTTP probes, a status from 200 through 399 is successful. Keep the response body minimal; the status code carries the decision.

Design endpoints around actions

A liveness endpoint should be cheap, local, and conservative. It should not fail merely because PostgreSQL, DNS, or a third-party API is temporarily unavailable. Restarting every application replica during a shared dependency outage removes capacity and adds load at the worst moment.

Readiness can represent whether the Pod can serve useful traffic. A required dependency may influence that decision, but use bounded checks and understand the blast radius. If every Pod marks itself unready during a brief database slowdown, the Service can lose all endpoints. Sometimes it is better to remain ready and return a controlled partial response; that is an application-specific decision.

A startup endpoint should become successful only after the minimum initialization required for the other probes to make sense. Do not use liveness with a huge initial delay to solve slow startup when a startup probe expresses the lifecycle directly.

HTTP is not the only probe mechanism. Kubernetes also supports TCP socket checks, commands executed in the container, and gRPC health checks. Choose the mechanism your application can implement reliably. A TCP success proves that a connection was accepted, not that a request can be served correctly. An exec probe consumes container resources and depends on the command existing in the image. Whatever mechanism you choose, keep its semantics documented so an operator knows what a success actually establishes.

Timing controls are a failure budget

• initialDelaySeconds delays the first check, but does not adapt to a startup that is sometimes faster or slower.
• periodSeconds sets check frequency.
• timeoutSeconds prevents one check from hanging indefinitely.
• failureThreshold requires consecutive failures before the failure action.
• successThreshold controls recovery; liveness and startup require the value to remain one.

Aggressive liveness settings can cause cascading failure under load: a busy process misses probes, restarts, shifts traffic to fewer replicas, and makes those replicas miss probes too. Begin with observed latency and failure data rather than copying timings from an unrelated workload.

Debug before changing thresholds

kubectl describe pod api-7d8f9c6b5c-abcde
kubectl get events --sort-by=.lastTimestamp
kubectl logs api-7d8f9c6b5c-abcde --previous
kubectl get pod api-7d8f9c6b5c-abcde -o wide
  

Pod events show the probe type, failure reason, and restart sequence. Previous-container logs are essential after a liveness restart. Confirm the path, named port, scheme, bind address, response time, and status code. A correct application endpoint still fails if it listens only on loopback while the kubelet probes the Pod IP.

Common probe mistakes

• Using the same deep dependency check for liveness and readiness.
• Returning success before startup work is actually complete.
• Running an expensive database query every few seconds from every replica.
• Setting timeouts below normal high-percentile latency.
• Ignoring probe failures in events and merely increasing thresholds.
• Assuming readiness failure restarts a container.

Probe behavior connects directly to safer Kubernetes rolling updates, because a Deployment should not replace capacity until new Pods become ready. It also interacts with CPU and memory configuration: severe CPU constraint can delay probe responses, while an OOM termination is not a liveness decision.

Frequently asked questions

Does readiness failure restart the container?

No. Readiness controls traffic eligibility. A liveness or startup failure can cause restart behavior after its configured threshold.

Do I need both startup and initialDelaySeconds?

Not automatically. A startup probe is usually clearer for variable or long initialization because it gates the other probes until success. Use delay values only when they reflect a measured need.

Should liveness check the database?

Usually no. A shared database outage is rarely repaired by restarting every client. Keep liveness focused on a local unrecoverable process condition.

Where is the precise behavior documented?

Use the official Kubernetes pages for liveness, readiness, and startup probe concepts and the task guide for configuring probes.

Test the failure actions

The linked mock checks whether you can distinguish traffic removal, restart behavior, startup gating, resource enforcement, and rollout capacity.

Quick quiz

DevOps

Docker and Kubernetes Production Readiness Mock Test

A practical assessment covering Docker Compose health checks, container DNS and storage, Kubernetes probes, resources, OOM diagnostics, and safer rolling updates.

15 questions25 min

Inline play

Start the trivia-style player right inside the article.

Play inlineView details

Practical takeaway: decide whether failure should delay startup, remove traffic, or restart a process, and then build the narrowest probe that supports exactly that action.