Kubernetes Probes Explained: Liveness, Readiness & Startup

When a container starts, Kubernetes knows its process is running, but it has no idea whether your application is actually healthy. A web server can be stuck in a deadlock, a service can still be loading a large cache, or an API can lose its database connection while the process stays alive. Kubernetes probes solve this problem by letting the kubelet check your application from the outside and react automatically.

This guide explains the three types of Kubernetes probes, the four ways to run a check, how to configure Kubernetes probes in YAML, how to tune their timing, and the mistakes that cause unnecessary restarts and outages.

What Are Kubernetes Probes?

Kubernetes probes are periodic health checks that the kubelet runs against each container in a pod. Every check returns one of three results: success, failure or unknown. Based on the result and the probe type, Kubernetes restarts the container, removes the pod from Service traffic, or holds back other checks until the application has started.

Kubernetes probes are defined per container in the pod spec, so a pod with a main application and a sidecar can have different health checks for each. Without Kubernetes probes, the only signal the cluster has is whether the main process has exited, which misses most real-world failures.

The Three Types of Kubernetes Probes

Liveness Probe

A liveness probe answers the question "is this container still working, or is it stuck?" If it fails a set number of times in a row, the kubelet kills the container and restarts it according to the pod's restart policy. Use it to recover from deadlocks and hung processes that cannot fix themselves.

Readiness Probe

A readiness probe answers "can this container accept traffic right now?" When it fails, nothing is restarted. Instead, the pod is marked as not ready and removed from the endpoints of every Service that selects it, so requests stop reaching it. When the check passes again, the pod is added back. Readiness is ideal for warm-up periods, temporary overload and dependencies that are briefly unavailable.

Startup Probe

A startup probe answers "has the application finished starting?" While a startup probe is configured and has not yet succeeded, the liveness and readiness checks for that container are disabled. This protects slow-starting applications, such as large Java services, from being killed before they are ready. Once the startup probe succeeds, it stops running and the other Kubernetes probes take over.

Quick Comparison of Kubernetes Probes

• Liveness: on failure, the container is restarted.
• Readiness: on failure, the pod is removed from Service endpoints, with no restart.
• Startup: on failure, the container is restarted; while it is running, liveness and readiness checks wait.

How Kubernetes Probes Perform a Check

All Kubernetes probes use one of four handlers:

• httpGet: sends an HTTP GET request to a path and port. Any status code from 200 to 399 counts as success. This is the most common choice for web applications and APIs.
• tcpSocket: tries to open a TCP connection on a port. Success means something is listening. Useful for databases, message brokers and other non-HTTP services.
• exec: runs a command inside the container. An exit code of 0 is success. It is flexible, but each check starts a new process, which adds overhead.
• grpc: calls the standard gRPC health checking protocol, so gRPC services do not need an extra health binary.

Timing Fields for Kubernetes Probes

All Kubernetes probes share the same tuning fields. Getting these right matters more than the handler you choose:

• initialDelaySeconds: how long to wait after the container starts before the first check. Default 0.
• periodSeconds: how often to run the check. Default 10.
• timeoutSeconds: how long to wait for a response before counting a failure. Default 1.
• failureThreshold: how many consecutive failures trigger the action. Default 3.
• successThreshold: how many consecutive successes are needed after a failure. Default 1, and it must be 1 for liveness and startup checks.
• terminationGracePeriodSeconds: an optional per-probe override of the grace period used when a liveness or startup failure kills the container.

A useful rule: the time a check can keep failing before action is roughly failureThreshold multiplied by periodSeconds. For a startup probe, that is the maximum time your application is allowed to boot.

Kubernetes Probes YAML Example

The example below configures all three Kubernetes probes for a web API that exposes separate health endpoints:

apiVersion: v1
kind: Pod
metadata:
  name: orders-api
spec:
  containers:
    - name: api
      image: example/orders-api:1.4.0
      ports:
        - containerPort: 8080
      startupProbe:
        httpGet:
          path: /healthz
          port: 8080
        periodSeconds: 5
        failureThreshold: 30
      livenessProbe:
        httpGet:
          path: /healthz
          port: 8080
        periodSeconds: 10
        timeoutSeconds: 2
        failureThreshold: 3
      readinessProbe:
        httpGet:
          path: /ready
          port: 8080
        periodSeconds: 5
        timeoutSeconds: 2
        failureThreshold: 2

Here the startup probe allows up to 30 x 5 = 150 seconds for the application to boot. After that, the liveness probe restarts the container if /healthz fails three times in a row, and the readiness probe takes the pod out of rotation whenever /ready fails.

Designing Health Endpoints for Kubernetes Probes

Kubernetes probes are only as good as the endpoints they call. Follow these guidelines:

• Keep liveness checks shallow. A liveness endpoint should confirm that the process can respond, not that every downstream dependency is up. If liveness checks the database and the database goes down, every pod restarts at once and recovery gets harder.
• Use dependencies in readiness carefully. Readiness can check critical dependencies, but if all replicas depend on the same one, they all become unready together and the Service has no endpoints. Decide whether a degraded response is better than no response.
• Make endpoints cheap and fast. Kubernetes probes run every few seconds on every replica, so avoid heavy queries or large memory allocations.
• Use separate paths. Distinct /healthz and /ready endpoints let you evolve each check independently.
• Do not require authentication on health paths, or the kubelet's requests will fail.

Kubernetes Probes and Zero-Downtime Deployments

Readiness checks are a key part of safe rolling updates. During a rollout, a Deployment only counts a new pod as available once it is ready, so a broken release with a failing readiness check stalls instead of replacing healthy pods. Combine Kubernetes probes with maxUnavailable, minReadySeconds and a clear rollback plan, covered in our guide on how to roll back a deployment safely.

For graceful shutdown, remember that a terminating pod is removed from endpoints, but in-flight requests may still arrive for a few seconds. Many teams add a short preStop sleep and handle SIGTERM properly so connections drain cleanly.

Common Mistakes with Kubernetes Probes

• Using the same endpoint for liveness and readiness. A temporary overload then causes restarts instead of just removing the pod from traffic.
• Timeouts that are too short. The default one-second timeout is easily exceeded during garbage collection or CPU throttling, producing false failures. Review your Kubernetes resource requests and limits as well.
• Using initialDelaySeconds instead of a startup probe. A fixed delay is either too long, slowing every start, or too short, killing slow starts. A startup probe adapts to real boot time.
• Checking dependencies in liveness. This turns a single outage into cascading restarts.
• Expensive exec commands. Running heavy scripts every few seconds wastes CPU across the cluster.
• Skipping Kubernetes probes entirely. Hung pods keep receiving traffic and users see errors.

How to Troubleshoot Failing Kubernetes Probes

When Kubernetes probes fail, start with kubectl describe pod followed by the pod name. The Events section shows messages such as "Liveness probe failed" or "Readiness probe failed" together with the HTTP status or error. Then:

1. Check the container logs with kubectl logs, adding --previous for a container that was restarted.
2. Test the endpoint from inside the pod with kubectl exec and a tool such as curl or wget.
3. Compare the probe timing with real startup time and response latency.
4. Look at restart counts and the CrashLoopBackOff state. Our guide to debugging crashing pods in Kubernetes covers this in depth.
5. Track restarts and readiness changes with Prometheus monitoring and alert when restart counts rise.

Best Practices Checklist for Kubernetes Probes

• Add a readiness probe to every container that serves traffic.
• Add a liveness probe only when the application can hang without exiting, and keep it shallow.
• Use a startup probe for any application that takes more than a few seconds to boot.
• Set timeouts and thresholds from measured latency, not guesses.
• Enforce Kubernetes probes on production workloads with policy tools such as OPA Gatekeeper.
• Review probe settings whenever startup time, resources or dependencies change.

Conclusion

Kubernetes probes turn "the process is running" into "the application is healthy and ready to serve". Use a startup probe for slow boots, a shallow liveness probe to recover from hangs, and a readiness probe to control traffic. Tune timeouts and thresholds from real measurements, keep health endpoints cheap, and watch restart counts closely. Configured well, Kubernetes probes make your services self-healing and your deployments safer. To build a strong foundation first, read our Kubernetes tutorial for beginners.