The health endpoint aggregates results from all registered HealthIndicator beans (built-in ones cover things like database connectivity, disk space, and message broker reachability) into one overall status (UP, DOWN, OUT_OF_SERVICE, or UNKNOWN). To add a custom check — say, verifying a downstream API is reachable — implement HealthIndicator (or extend AbstractHealthIndicator) and register it as a bean; Actuator automatically discovers and includes it in the aggregated health report.

Intermediate5 min

AccentureCapgeminiCognizantOracleIBMAmazon

#HealthIndicator#/actuator/health

How does the /actuator/health endpoint work, and how do you add a custom health check?

One DOWN Indicator Takes Down the Whole Aggregate Status

The overall /actuator/health status is DOWN if any single registered HealthIndicator reports DOWN — this all-or-nothing aggregation is exactly why health checks feeding into a Kubernetes liveness/readiness probe need to be chosen carefully: a health indicator checking a non-critical, flaky downstream dependency can inadvertently cause the entire pod to be marked unhealthy and restarted, even though the core application itself is functioning fine.

Custom Health Indicator

java

@Component
class DownstreamApiHealthIndicator implements HealthIndicator {
    @Override
    public Health health() {
        boolean reachable = pingDownstreamApi();
        return reachable ? Health.up().build() : Health.down().withDetail("reason", "unreachable").build();
    }
}