Docker Health Checks for Spring Boot with Actuator

Intermediate·2 min read·

Fast recall

Quick revision

Core answer

Use the HEALTHCHECK instruction in Dockerfile to define a command Docker runs to verify the container is healthy. For Spring Boot, check /actuator/health using wget or curl. This tells Docker Compose to wait until the app is ready before routing traffic, and lets Kubernetes know when the pod is ready to serve requests.

Interview Answer2 min

A Docker health check tells the container runtime whether your application is actually ready to serve traffic — not just whether the process is running. Without a health check, Docker Compose marks a container Up the moment the process starts, even if Spring Boot is still initializing.

Health check configuration

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 CMD curl -f http://localhost:8080/actuator/health || exit 1 — the start-period is critical for Spring Boot: it gives the JVM time to start and warm up before health checks begin counting failures
Use /actuator/health rather than any arbitrary endpoint — Spring Boot's health endpoint aggregates all health indicators (database connectivity, disk space, custom indicators) into one response; a simple /ping that returns 200 OK does not verify database connectivity
Add management.endpoint.health.probes.enabled=true to enable Kubernetes-specific /actuator/health/liveness and /actuator/health/readiness endpoints — Spring Boot 2.3+ supports these separately, allowing different behaviors for liveness (is the JVM responding?) versus readiness (is the application ready for traffic?)

Docker Compose depends_on integration

A healthcheck on the postgres service combined with condition: service_healthy in the Spring Boot service's depends_on ensures the application starts only after the database is accepting connections — prevents the most common startup failure in compose-based environments
Without the condition: service_healthy, Compose only guarantees that the postgres container has started, not that it is ready — the Spring Boot container begins before the database and fails to establish a connection pool

Kubernetes probe alignment

In Kubernetes, the Dockerfile HEALTHCHECK is ignored — liveness and readiness are configured directly in the pod spec; use Spring Boot Actuator's dedicated probe endpoints for both
Make liveness more lenient than readiness: a failed liveness check restarts the pod (potentially causing a cascade), while a failed readiness check only removes the pod from the load balancer — the correct response for a temporarily overloaded pod

Interview-ready guide

Interview answer

Health check configuration

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 CMD curl -f http://localhost:8080/actuator/health || exit 1 — the start-period is critical for Spring Boot: it gives the JVM time to start and warm up before health checks begin counting failures
Use /actuator/health rather than any arbitrary endpoint — Spring Boot's health endpoint aggregates all health indicators (database connectivity, disk space, custom indicators) into one response; a simple /ping that returns 200 OK does not verify database connectivity
Add management.endpoint.health.probes.enabled=true to enable Kubernetes-specific /actuator/health/liveness and /actuator/health/readiness endpoints — Spring Boot 2.3+ supports these separately, allowing different behaviors for liveness (is the JVM responding?) versus readiness (is the application ready for traffic?)

Docker Compose depends_on integration

A healthcheck on the postgres service combined with condition: service_healthy in the Spring Boot service's depends_on ensures the application starts only after the database is accepting connections — prevents the most common startup failure in compose-based environments
Without the condition: service_healthy, Compose only guarantees that the postgres container has started, not that it is ready — the Spring Boot container begins before the database and fails to establish a connection pool

Kubernetes probe alignment

In Kubernetes, the Dockerfile HEALTHCHECK is ignored — liveness and readiness are configured directly in the pod spec; use Spring Boot Actuator's dedicated probe endpoints for both
Make liveness more lenient than readiness: a failed liveness check restarts the pod (potentially causing a cascade), while a failed readiness check only removes the pod from the load balancer — the correct response for a temporarily overloaded pod

03 · Deep dive