By WebNest Studio Engineering Team
Spring Boot Tutorial
Health Checks, Readiness and Liveness Probes
Load balancers and orchestrators like Kubernetes constantly ask your application two different questions. Liveness: "Is this process broken beyond repair? Should I restart it?" Readiness: "Can this instance handle traffic right now? Should I send it requests?" Answering these correctly is what makes rolling deployments, autoscaling and self-healing work without dropped requests.
This lesson covers Actuator's health endpoint and indicators, custom health checks, liveness and readiness state, health groups, how Spring Boot exposes Kubernetes probes, and how graceful shutdown fits in.
The Health Endpoint
/actuator/health aggregates HealthIndicators: Spring Boot adds indicators for the database, disk space, Redis, MongoDB, RabbitMQ, Kafka, mail server and more, depending on your dependencies. The overall status is UP only if all indicators are UP. Details are hidden by default; show them to authorised users with management.endpoint.health.show-details=when-authorized.
Liveness vs Readiness
These must not be confused. Liveness should reflect only the application's internal state — a deadlock or a corrupted state that a restart would fix. It must not include the database: if the database is down, restarting every pod will not help and causes a restart storm. Readiness says whether the instance should receive traffic: false during startup, while warming caches, during shutdown, or when a critical dependency is unavailable.
Probes in Spring Boot
Spring Boot exposes /actuator/health/liveness and /actuator/health/readiness health groups, automatically on Kubernetes or with management.endpoint.health.probes.enabled=true. Its ApplicationAvailability tracks LivenessState and ReadinessState: readiness becomes ACCEPTING_TRAFFIC only after runners have completed, and switches to REFUSING_TRAFFIC at the start of graceful shutdown. You can add indicators to a group or change state yourself by publishing an AvailabilityChangeEvent.
Custom Health Indicators
Implement HealthIndicator (or AbstractHealthIndicator) to report the state of a dependency Spring Boot does not know about, such as a partner API or a licence server. Keep checks fast and cached — probes run every few seconds on every instance.
Examples
Configuration and endpoint output
# application.yml
management:
endpoint:
health:
show-details: when-authorized
probes:
enabled: true
group:
readiness:
include: readinessState, db, redis # ready only if DB and Redis are reachable
endpoints:
web:
exposure:
include: health
GET /actuator/health/liveness -> 200 {"status":"UP"}
GET /actuator/health/readiness -> 200 {"status":"UP"}
(database stopped)
GET /actuator/health/readiness -> 503 {"status":"OUT_OF_SERVICE"}
GET /actuator/health/liveness -> 200 {"status":"UP"} (no pointless restart)
A custom health indicator for a partner API
@Component("paymentGateway")
public class PaymentGatewayHealthIndicator implements HealthIndicator {
private final RestClient client;
public PaymentGatewayHealthIndicator(RestClient.Builder builder) {
this.client = builder.baseUrl("https://pay.example.com").build();
}
@Override
public Health health() {
try {
ResponseEntity<Void> r = client.get().uri("/health").retrieve().toBodilessEntity();
return Health.up().withDetail("status", r.getStatusCode().value()).build();
} catch (Exception e) {
return Health.down(e).withDetail("endpoint", "https://pay.example.com/health").build();
}
}
}
GET /actuator/health (as admin)
{"status":"DOWN","components":{"db":{"status":"UP"},"diskSpace":{"status":"UP"},
"paymentGateway":{"status":"DOWN","details":{"endpoint":"https://pay.example.com/health","error":"...Connection refused"}}}}
Refusing traffic while a cache warms up
@Component
public class CacheWarmer {
private final ApplicationEventPublisher events;
private final CatalogCache cache;
public CacheWarmer(ApplicationEventPublisher events, CatalogCache cache) {
this.events = events;
this.cache = cache;
}
@EventListener(ApplicationReadyEvent.class)
public void warm() {
AvailabilityChangeEvent.publish(events, this, ReadinessState.REFUSING_TRAFFIC);
cache.loadAll(); // takes ~20 s
AvailabilityChangeEvent.publish(events, this, ReadinessState.ACCEPTING_TRAFFIC);
}
}
0-20 s after start: /actuator/health/readiness -> 503 (Kubernetes sends no traffic)
after warm-up: /actuator/health/readiness -> 200
Common Mistakes
- Including the database in the liveness probe, causing all pods to restart during a database outage.
- Pointing Kubernetes probes at /actuator/health instead of the separate liveness and readiness groups.
- Writing slow health checks that call expensive APIs on every probe.
- Showing full health details publicly, revealing infrastructure information.
- Ignoring readiness during startup, so traffic arrives before caches and connections are ready.
Exercise
Using the lesson's Configuration and endpoint output example, create a small implementation or design sketch that demonstrates /actuator/health aggregates HealthIndicators for your dependencies.. Add a test case or scenario that would catch Including the database in the liveness probe, causing all pods to restart during a database outage., and describe the expected result.
Show hints
- Start with The Health Endpoint and compare your approach with Configuration and endpoint output. Identify the decision or behavior the lesson recommends.
- Walk through your scenario step by step. Confirm that it follows /actuator/health aggregates HealthIndicators for your dependencies. and that it would catch the failure described by Including the database in the liveness probe, causing all pods to restart during a database outage..
Quick quiz
1. Which choice is a mistake to avoid in Health Checks, Readiness and Liveness Probes?
- A. /actuator/health aggregates HealthIndicators for your dependencies.
- B. Including the database in the liveness probe, causing all pods to restart during a database outage.
- C. Pointing Kubernetes probes at /actuator/health instead of the separate liveness and readiness groups.
Show answer
B. Avoid this approach: Including the database in the liveness probe, causing all pods to restart during a database outage. The lesson recommends: /actuator/health aggregates HealthIndicators for your dependencies.
Interview questions
How would you apply the guidance in The Health Endpoint to a real task, and what failure would you guard against?
Show answer
/actuator/health aggregates HealthIndicators for your dependencies. Apply this in The Health Endpoint; the example Configuration and endpoint output shows one way to do it. Avoid Including the database in the liveness probe, causing all pods to restart during a database outage. and explain how your implementation or design prevents that failure.
Key Points to Remember
- /actuator/health aggregates HealthIndicators for your dependencies.
- Liveness = restart if broken (internal state only); readiness = send traffic or not.
- Spring Boot exposes /actuator/health/liveness and /readiness groups for Kubernetes.
- Custom HealthIndicators report dependencies Spring Boot does not know.
- Publish AvailabilityChangeEvent to control readiness, e.g. during warm-up.
Practice in the playground
Write and run your own code for this topic, or start from the exercise or an example. Runs plain Java 17. Frameworks such as Spring, and databases, are not available here. Your code for each topic is kept in this browser.
Run the examples
Change an input, predict the result, then compare it with the output. Explain why the result changes.
These examples need a JDK project with their libraries on your computer, so they can be copied but not run here. Codelab runs Python, FastAPI backends with SQLite, plain Java 17 and HTML/CSS/JavaScript.
Written by
WebNest Studio Engineering Team
Practical lessons from developers working with Java, Python, React, databases and production systems.
Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering