Kubernetes Container Probes
Learn Kubernetes liveness, readiness and startup probes with practical YAML examples, probe types, failure behavior, troubleshooting and production best practices.
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
Liveness vs Readiness vs Startup
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.
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
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.
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.
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
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/