kubernetes

Kubernetes Container Probes

Learn Kubernetes liveness, readiness and startup probes with practical YAML examples, probe types, failure behavior, troubleshooting and production best practices.

By Shubhankar Tripathi • • 5 min read

Kubernetes Container Probes: Liveness, Readiness and Startup Probes

How Kubernetes detects application health, controls traffic and handles slow-starting containers

Introduction

A container process being alive does not necessarily mean that an application is healthy or ready to serve users. A web application may have started its process but still be loading configuration, warming caches, connecting to dependencies or recovering from an internal problem.

Kubernetes provides container probes so that the kubelet can evaluate application health and readiness. The three primary probe types are liveness, readiness and startup probes. Each answers a different operational question, and using the wrong probe can cause unnecessary restarts, send traffic to an unready application or make a slow-starting application appear unhealthy.

This article explains the three probe types, how they work, probe mechanisms, configuration fields, real-world patterns, failure behavior, troubleshooting and production best practices.

What Is a Kubernetes Probe?

A probe is a diagnostic performed by the kubelet against a container. Kubernetes uses the result of the probe according to the probe type. The kubelet can execute a command in the container, make an HTTP request, attempt a TCP connection or, where supported by the configuration, use gRPC health checking.

The important design principle is that probes should represent meaningful application health signals. A probe should not merely confirm that a process exists if the real requirement is that the application can serve requests.

The Three Probe Types

Probe

Primary question

Typical consequence of failure

Liveness

Is the running application still healthy enough to continue?

The kubelet can restart the container.

Readiness

Is the application currently ready to receive traffic?

The Pod is treated as not ready for Service traffic.

Startup

Has this slow-starting application finished starting?

Startup checking continues until success or the configured failure threshold is reached; liveness and readiness checks are held back while the startup probe has not succeeded.


Liveness vs Readiness vs Startup

Aspect

Liveness

Readiness

Startup

Main purpose

Detect an unhealthy running container.

Control whether the application receives traffic.

Protect slow-starting applications during initialization.

Failure means

Container is considered unhealthy for liveness.

Container is not ready.

Startup has not succeeded.

Can cause restart?

Yes, kubelet may restart the container.

No, readiness failure itself does not restart the container.

Yes, if startup failure reaches the configured threshold, the container is considered unhealthy and can be restarted.

Traffic impact

Not directly a traffic-routing signal.

Yes.

Not directly a traffic-routing signal.

Typical use

Deadlock or unrecoverable application state.

Temporary overload, dependency unavailability or warm-up state.

Long initialization time.


1. Kubernetes Liveness Probe

A liveness probe tells Kubernetes how to determine whether a running container should be considered alive. If a liveness probe repeatedly fails according to its configured thresholds, the kubelet can restart the container.

Liveness is most useful for failures from which the application cannot recover without a restart. Examples include an application deadlock, a permanently stuck internal state or a condition where the process remains running but cannot perform its intended function.

Example: HTTP Liveness Probe

apiVersion: v1

kind: Pod

metadata:

  name: liveness-demo

spec:

  containers:

    - name: app

      image: nginx:1.29

      ports:

        - containerPort: 80

      livenessProbe:

        httpGet:

          path: /

          port: 80

        initialDelaySeconds: 10

        periodSeconds: 10

        timeoutSeconds: 2

        failureThreshold: 3

The exact timing should be designed from the application's behavior. Avoid choosing very aggressive values simply because they make failure detection appear faster.

When Liveness Is Appropriate

• The process can remain alive while the application is permanently stuck.

• A restart is a valid and tested recovery mechanism.

• The health endpoint represents a condition where restarting the container is appropriate.

When Liveness Can Be Dangerous

• The probe checks a dependency that may be temporarily unavailable.

• The application needs a long time to recover from load or transient conditions.

• The probe is more aggressive than the application's normal startup or recovery behavior.

• A temporary dependency failure causes every replica to restart at the same time.

2. Kubernetes Readiness Probe

A readiness probe answers a different question: can this application instance currently receive traffic? A container can be running but not ready. This is normal during startup, warm-up, temporary overload or dependency recovery.

When a readiness probe fails, Kubernetes does not restart the container merely because readiness failed. Instead, the Pod is treated as not ready, which affects whether it is considered an available endpoint for Services.

Example: HTTP Readiness Probe

apiVersion: v1

kind: Pod

metadata:

  name: readiness-demo

spec:

  containers:

    - name: app

      image: nginx:1.29

      ports:

        - containerPort: 80

      readinessProbe:

        httpGet:

          path: /

          port: 80

        periodSeconds: 5

        timeoutSeconds: 2

        failureThreshold: 3

Readiness is particularly important for rolling deployments. A new Pod can be running while the application is still warming up, and readiness prevents that Pod from being treated as ready before it is actually capable of serving traffic.

Readiness Does Not Mean 'Restart Me'

This is one of the most important distinctions in Kubernetes health checking. A readiness failure is a traffic-availability signal, not a restart signal. If the application is alive but temporarily unable to serve requests, readiness is usually the correct mechanism.

3. Kubernetes Startup Probe

A startup probe is designed for applications that require significant time to initialize. When a startup probe is configured, Kubernetes can use it to determine when startup has completed before applying liveness and readiness probe behavior.

This prevents a slow-starting application from being restarted by a liveness probe before it has had enough time to initialize.

Example: Startup + Liveness + Readiness

apiVersion: v1

kind: Pod

metadata:

  name: probe-demo

spec:

  containers:

    - name: app

      image: nginx:1.29

      ports:

        - containerPort: 80


      startupProbe:

        httpGet:

          path: /

          port: 80

        periodSeconds: 5

        failureThreshold: 30


      livenessProbe:

        httpGet:

          path: /

          port: 80

        periodSeconds: 10

        failureThreshold: 3


      readinessProbe:

        httpGet:

          path: /

          port: 80

        periodSeconds: 5

        failureThreshold: 3

In this design, the startup probe provides the startup window. Once startup succeeds, the liveness and readiness probes can perform their normal jobs.

Why Startup Probes Matter

• Large applications may need substantial time to initialize.

• Applications may load machine-learning models or large datasets.

• JVM applications may have long startup or warm-up periods.

• Applications may perform migrations or cache initialization before becoming usable.

• A startup probe prevents an overly aggressive liveness probe from treating normal initialization as failure.

Probe Mechanisms

Kubernetes supports several probe mechanisms. The correct mechanism depends on how the application exposes health information.

Mechanism

How it works

Good fit

HTTP GET

Kubelet sends an HTTP request to the configured endpoint.

HTTP/HTTPS services with a dedicated health endpoint.

TCP socket

Kubelet attempts to establish a TCP connection.

Services where successful port availability is a useful health signal.

Exec

Kubelet executes a command inside the container.

Applications that expose a reliable local health command.

gRPC

Kubelet performs a gRPC health check.

Applications implementing the applicable gRPC health checking protocol.


HTTP Probe in Detail

An HTTP probe can specify a path and port and can use HTTP or HTTPS. The endpoint should be intentionally designed for health checking rather than simply reusing a normal business endpoint.

livenessProbe:

  httpGet:

    path: /healthz

    port: 8080

  periodSeconds: 10

  timeoutSeconds: 2

A good health endpoint should be lightweight and predictable. Avoid making the endpoint perform expensive database queries or long dependency chains unless that behavior is deliberately part of the health contract.

TCP Probe in Detail

readinessProbe:

  tcpSocket:

    port: 8080

  periodSeconds: 5

  timeoutSeconds: 2

A TCP probe verifies that a connection can be established. It does not prove that the application is returning correct HTTP responses or that business operations are functioning correctly.

Exec Probe in Detail

livenessProbe:

  exec:

    command:

      - /bin/sh

      - -c

      - test -f /tmp/application-healthy

  periodSeconds: 10

Exec probes can be useful when an application provides a local diagnostic command. However, they execute a process in the container, so their overhead and security implications should be considered.

gRPC Probes

For applications using gRPC health checking, Kubernetes supports a gRPC probe configuration. The application must expose a compatible health checking endpoint and the configured service name, when used, must match the application's health semantics.

livenessProbe:

  grpc:

    port: 50051

  periodSeconds: 10

Use the gRPC probe when the application's health contract is naturally represented through gRPC health checking rather than adding an unrelated HTTP endpoint.

Important Probe Configuration Fields

Field

Purpose

initialDelaySeconds

Number of seconds after container start before the probe is initiated. It is useful when the application needs an initial delay and no startup probe is being used.

periodSeconds

How often the probe is performed.

timeoutSeconds

How long a probe can take before it is treated as failed.

successThreshold

Minimum consecutive successes required for the probe to be considered successful. Readiness commonly benefits from explicit use of this field.

failureThreshold

Number of consecutive failures before the probe is considered failed.

terminationGracePeriodSeconds

Optional per-probe termination grace behavior for supported probe configuration; otherwise Pod-level termination behavior applies.


Probe timing should be selected from real application startup, recovery and response-time characteristics rather than copied blindly from another workload.

Probe Lifecycle and Application Startup

A common production pattern is to combine the three probes rather than trying to make one endpoint perform every role.

Lifecycle stage

Probe role

Application process starts

Startup probe protects the initialization period.

Application finishes initialization

Startup succeeds.

Application is temporarily unable to serve

Readiness can fail without restarting the container.

Application becomes permanently unhealthy

Liveness can fail and trigger container restart.


A Practical Mental Model

Think about the three probes as three different questions:

1. Startup: 'Have you finished starting?'

2. Readiness: 'Can I send users to you right now?'

3. Liveness: 'Are you still healthy enough to keep running?'

Common Architecture Pattern

                    Kubernetes Pod

                         |

              +----------+----------+

              |                     |

        Application              Probes

              |                     |

              |       +-------------+-------------+

              |       |             |             |

              |    Startup       Readiness     Liveness

              |       |             |             |

              +-------+-------------+-------------+

                      |

              Kubelet uses results

                      |

          +-----------+-----------+

          |                       |

      Traffic decision        Restart decision

       (readiness)              (liveness)

The diagram illustrates the conceptual separation. Probes are evaluated by the kubelet, while readiness also influences whether the Pod is considered available for Service traffic.

Designing Good Health Endpoints

A health endpoint should reflect a clear operational contract. The correct contract depends on the probe.

Health endpoint characteristic

Why it matters

Fast

Probes run repeatedly, so expensive checks can create unnecessary load.

Deterministic

Flaky responses can create false failures.

Specific to the probe's purpose

Liveness, readiness and startup represent different decisions.

Observable

Operators should be able to understand why a check is failing.

Safe

Health checks should not mutate application state.


Should Liveness Check Dependencies?

Usually, a liveness check should be conservative about external dependencies. If a database or downstream service temporarily becomes unavailable, restarting every application container may amplify the incident rather than recover from it.

Readiness is often a better place for a temporary dependency-related condition when the desired behavior is to stop sending new traffic to an instance without repeatedly restarting it.

This is a design recommendation, not a universal rule. Some applications may intentionally define liveness in terms of a critical dependency, but that decision should be deliberate and tested.

Readiness During Rolling Updates

Readiness is especially important during Deployment rollouts. A newly created Pod can be running while the application is still initializing. If readiness is correctly configured, the Pod is not treated as ready until the application can serve traffic.

This helps reduce the chance of routing requests to a process that has started but is not yet prepared to serve them.

Failure Scenarios

Scenario 1: Slow Application Startup

Problem: The application normally takes 90 seconds to initialize, but liveness starts checking after a short delay and begins failing.

Better approach: Use a startup probe with a failure threshold and period that provide a realistic startup window.

Result: The application gets enough time to initialize before normal liveness behavior takes effect.

Scenario 2: Database Temporarily Unavailable

Problem: The application process is healthy, but its database is temporarily unavailable.

Potential approach: Allow readiness to fail if the application should stop receiving traffic while the dependency is unavailable, without automatically restarting the application.

Result: Traffic can be withheld while the process remains available to recover when the dependency returns.

Scenario 3: Application Deadlock

Problem: The process is still running, but it can no longer make progress.

Potential approach: A liveness endpoint can detect the unrecoverable condition.

Result: The kubelet can restart the container according to the Pod's restart behavior.

Troubleshooting Probe Failures

Step 1: Inspect the Pod

kubectl get pod <pod-name>

kubectl describe pod <pod-name>

The Events section often provides useful information about failed probes and container restarts.

Step 2: Inspect Logs

kubectl logs <pod-name> -c <container-name>

kubectl logs <pod-name> -c <container-name> --previous

The previous-container logs are useful when a liveness failure caused the container to restart.

Step 3: Inspect the Actual Probe Endpoint

kubectl exec -it <pod-name> -c <container-name> -- sh

From inside the container, verify that the configured path, port, command or local health mechanism behaves as expected.

Step 4: Inspect the Pod Specification

kubectl get pod <pod-name> -o yaml

Confirm that the probe configuration deployed to the cluster matches the configuration you intended.

Common Probe Problems

Problem

Likely cause

Typical fix

Readiness continuously fails

Wrong endpoint, port, startup state or application dependency.

Validate the readiness contract and endpoint.

Liveness causes frequent restarts

Probe is too aggressive or health endpoint is unstable.

Increase tolerance and redesign the liveness check.

Startup probe times out

Startup window is too short.

Measure startup time and adjust the startup probe.

Probe returns success but users get errors

Health endpoint is too shallow.

Design a health signal that represents the intended operational state.

Exec probe consumes resources

Command is expensive or runs too frequently.

Simplify the command and adjust frequency.

TCP probe succeeds but application is unhealthy

Port is open but application logic is broken.

Use an application-level health check when appropriate.


Common Mistakes

• Using liveness as a generic dependency checker.

• Using readiness as a restart mechanism.

• Using initialDelaySeconds as a substitute for understanding startup behavior when a startup probe is more appropriate.

• Making health endpoints perform expensive database or external-service operations.

• Setting failureThreshold and periodSeconds without measuring application behavior.

• Using the same health endpoint for every probe without considering the different decisions each probe makes.

• Forgetting to verify probe ports after changing container ports.

• Ignoring probe failures in monitoring and alerting.

• Testing probes only under normal load and not during startup, dependency failure or resource pressure.

Production Best Practices

• Use readiness to represent whether a Pod should receive application traffic.

• Use liveness only when restarting the container is an appropriate recovery action.

• Use startup probes for applications with significant initialization time.

• Keep health checks lightweight, fast and deterministic.

• Design separate health semantics when startup, readiness and liveness genuinely require different answers.

• Measure real startup and recovery times before selecting probe thresholds.

• Test probes during deployments, dependency outages and resource pressure.

• Monitor restart counts and probe failures together so that operators can distinguish application failure from probe misconfiguration.

• Avoid making all replicas depend on the same fragile health check or external dependency.

• Document why each probe exists and what operational decision it is intended to drive.

Hands-On Lab: Configure All Three Probes

Step 1: Create a Pod

cat > probe-demo.yaml <<'EOF'

apiVersion: v1

kind: Pod

metadata:

  name: probe-demo

spec:

  containers:

    - name: app

      image: nginx:1.29

      ports:

        - containerPort: 80


      startupProbe:

        httpGet:

          path: /

          port: 80

        periodSeconds: 5

        failureThreshold: 30


      readinessProbe:

        httpGet:

          path: /

          port: 80

        periodSeconds: 5

        timeoutSeconds: 2

        failureThreshold: 3


      livenessProbe:

        httpGet:

          path: /

          port: 80

        periodSeconds: 10

        timeoutSeconds: 2

        failureThreshold: 3

EOF


kubectl apply -f probe-demo.yaml

Step 2: Observe the Pod

kubectl get pod probe-demo

kubectl describe pod probe-demo

kubectl get pod probe-demo -o yaml

Step 3: Experiment

Change the readiness path to an endpoint that does not exist. Observe that the container can remain Running while readiness fails. Restore the endpoint and observe readiness recover.

Then experiment with startup timing using a deliberately slow-starting test application. The goal is to understand how startup protection changes the behavior of liveness checks.

Interview Questions

1. What is the difference between liveness and readiness?

Answer: Liveness determines whether a container is healthy enough to continue running; readiness determines whether the application is currently ready to receive traffic.

2. Does a readiness probe failure restart a container?

Answer: No. Readiness failure itself does not restart the container.

3. Why use a startup probe?

Answer: To protect slow-starting applications from being treated as unhealthy by liveness and readiness checks before startup has completed.

4. What happens when a liveness probe repeatedly fails?

Answer: The kubelet can restart the affected container according to the Pod's configured restart behavior.

5. What happens when a readiness probe fails?

Answer: The Pod is treated as not ready, so it should not receive normal Service traffic while the readiness condition remains false.

6. Can a Pod be Running but not Ready?

Answer: Yes. Running and Ready represent different aspects of Pod state.

7. Why can an aggressive liveness probe cause an outage?

Answer: It can repeatedly restart otherwise recoverable applications or cause synchronized restarts across replicas.

8. What probe should usually represent temporary inability to serve traffic?

Answer: Readiness is generally the appropriate signal when the application should remain running but should temporarily stop receiving traffic.

9. What are common probe mechanisms?

Answer: HTTP GET, TCP socket, exec and gRPC health checking.

10. What is the role of failureThreshold?

Answer: It controls how many consecutive failures are required before the probe is considered failed.

11. What is the role of periodSeconds?

Answer: It controls how frequently the probe is performed.

12. Why should health endpoints be lightweight?

Answer: They are invoked repeatedly and expensive health checks can create additional load or false failures.

Production Checklist

• Every liveness probe has a clear restart rationale.

• Every readiness probe has a clear traffic-availability rationale.

• Slow-starting applications have an appropriate startup strategy.

• Probe endpoints are lightweight and deterministic.

• Probe timing is based on measured application behavior.

• Probe failures are visible in logs, events and monitoring.

• The application has been tested during startup and graceful recovery.

• Health checks do not create unnecessary dependency storms.

• Rolling deployments have been tested with readiness behavior.

• Operators know how to diagnose probe failures with kubectl describe and logs.

Summary

Kubernetes liveness, readiness and startup probes are not interchangeable. Liveness answers whether a running application should continue running. Readiness answers whether it should currently receive traffic. Startup protects applications that need substantial time to initialize before normal health checking becomes meaningful.

The best probe configuration reflects the application's real operational behavior. A probe should be simple enough to execute reliably but meaningful enough to drive the intended Kubernetes decision. Poorly designed probes can cause unnecessary restarts, hide failures or route traffic to applications that are not ready.

For production systems, treat probes as part of the application's reliability design rather than as YAML settings added at the end of deployment development.

Related BitCodeMatrix Topics

• Kubernetes Pod Lifecycle: From Creation to Termination

• Kubernetes Init Containers vs Sidecar Containers

• Kubernetes Pod Explained: Architecture, Lifecycle, States and Restart Behavior

• Kubernetes Deployment Explained: Rolling Updates, Rollbacks and Revision History

• Kubernetes Deployment Strategies: Rolling, Recreate, Blue-Green and Canary

• Kubernetes ReplicaSet Explained: How Kubernetes Maintains Pod Availability

• Kubernetes Services and Service Discovery

• Kubernetes Scheduling: Requests, Limits, Affinity, Taints and Tolerations

Official Kubernetes References

• Kubernetes Documentation — Configure Liveness, Readiness and Startup Probes: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/

• Kubernetes Documentation — Pod Lifecycle: https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/

• Kubernetes Documentation — Container Probes: https://kubernetes.io/docs/concepts/configuration/liveness-readiness-startup-probes/

• Kubernetes Documentation — Pods: https://kubernetes.io/docs/concepts/workloads/pods/