Spring Boot Health Checks with Liveness and Readiness Probes

1. The Core Concepts: Liveness, Readiness, and Startup Probes

To build resilient systems, Kubernetes needs to be able to ask your application two fundamental questions:

1. "Are you alive?": If the answer is no, the application has irrecoverably failed, and the container should be restarted.
2. "Are you ready to serve traffic?": If the answer is no, the application is temporarily busy or still initializing and shouldn't receive new requests.

Kubernetes uses probes to ask these questions. Let's look at the three main types.

The Liveness Probe acts as a safeguard against application freezes or deadlocks. If the probe fails, Kubernetes assumes the application is in a broken state and restarts it, hoping to return it to a healthy state.

The Readiness Probe is for managing traffic flow. An application might be "alive" but not "ready"—for example, it might be warming up a cache or waiting for a database connection during startup. By failing the readiness probe, the application tells Kubernetes, "I'm alive, but don't send me any traffic just yet."

To get a more detailed conceptual overview and see how these probes are configured in a Kubernetes manifest, please watch the following video.

2. Spring Boot Integration: The Actuator Health Endpoints

Now that we understand what Kubernetes needs, how does our Spring Boot application provide the answers? The solution is Spring Boot Actuator.

Since Spring Boot 2.3, Actuator includes first-class support for Kubernetes probes. When you add the Actuator dependency and enable the feature, Spring Boot automatically exposes dedicated health endpoints that Kubernetes can poll.

Let's walk through the implementation steps.

Step 1: Add the Actuator Dependency

First, ensure your pom.xml includes the spring-boot-starter-actuator:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Step 2: Enable the Probe Endpoints

Next, in your application.properties or application.yml, you need to enable the probe-specific endpoints.

For application.yml:

management:
  endpoint:
    health:
      probes:
        enabled: true

This single property tells Spring Boot to expose two crucial endpoints:

• /actuator/health/liveness: For the Liveness Probe. It returns HTTP 200 OK as long as the application context is running. If the application's internal state becomes broken, it will return HTTP 503 Service Unavailable.
• /actuator/health/readiness: For the Readiness Probe. It returns HTTP 200 OK only after the application is fully started and ready to accept traffic. During startup, it will return HTTP 503.

To learn more about how Spring Boot manages the internal states for liveness and readiness, the following article provides an excellent deep dive.

3. Configuring the Probes in Kubernetes

With our Spring Boot application now exposing the correct endpoints, the final step is to configure our Kubernetes Deployment to use them. This is done by adding livenessProbe and readinessProbe sections to the container specification in your deployment.yaml.

The configuration tells the kubelet on each node how and when to check your application's health.

# In your deployment.yaml, inside spec.template.spec.containers[]
...
ports:
  - containerPort: 8080
livenessProbe:
  httpGet:
    path: /actuator/health/liveness
    port: 8080
  initialDelaySeconds: 15  # Wait 15s before first probe
  periodSeconds: 20      # Probe every 20s
  failureThreshold: 3      # Restart after 3 consecutive failures
readinessProbe:
  httpGet:
    path: /actuator/health/readiness
    port: 8080
  initialDelaySeconds: 5   # Wait 5s before first probe
  periodSeconds: 10      # Probe every 10s
...

Let's break down the key parameters:

• httpGet: Specifies that the probe is an HTTP GET request to the given path and port.
• initialDelaySeconds: How long Kubernetes should wait after the container starts before sending the first probe. This is critical! If this value is too low for a Spring Boot application (which can take several seconds to start), the probes will fail, and Kubernetes might get stuck in a crash loop.
• periodSeconds: The interval between probes.
• failureThreshold: The number of consecutive probe failures required before Kubernetes takes action (restarting for liveness, removing from service for readiness).

Tuning these values is essential for a stable system. A too-aggressive liveness probe can restart your application unnecessarily, while a too-lenient one can leave a deadlocked service running for too long.

livenessProbe:
  httpGet:
    path: /actuator/health/liveness
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5
  failureThreshold: 3

4. Custom Health Indicators and Graceful Shutdown

For senior-level roles, demonstrating knowledge beyond the basics is key.

• Custom Health Indicators: What if "healthy" means your application can connect to its database? Spring Boot allows you to create custom health checks by implementing the HealthIndicator interface. Actuator automatically aggregates these custom checks into the main /actuator/health endpoint. For example, if your database health indicator fails, the main health endpoint will also fail.

• Graceful Shutdown: When a liveness probe fails, Kubernetes sends a SIGTERM signal to the container, asking it to shut down gracefully. If the container doesn't shut down within a timeout period (default 30s), it sends a SIGKILL, terminating it forcefully. A robust application should handle SIGTERM to finish in-flight requests and release resources. You can enable this in Spring Boot:

  server:
    shutdown: graceful
  spring:
    lifecycle:
      timeout-per-shutdown-phase: 20s
  

Conclusion

You have now learned how to implement a fundamental pattern for building resilient, self-healing applications in Kubernetes. By correctly configuring liveness and readiness probes, you allow Kubernetes to become an active manager of your application's health, not just a passive host.

Key Takeaways:

• Liveness Probes restart unhealthy containers to recover from fatal errors like deadlocks.
• Readiness Probes control traffic flow, ensuring requests are only sent to fully initialized and ready services.
• Spring Boot Actuator provides the /actuator/health/liveness and /actuator/health/readiness endpoints needed by Kubernetes.
• Configuring probes in your Deployment.yaml is crucial, and tuning parameters like initialDelaySeconds and failureThreshold is essential for stability.
• Advanced concepts like custom HealthIndicators and graceful shutdown elevate your application from simply "running" to "production-ready."

Preview of the Next Lesson:
Our application is now deployed, exposed, configured, and self-healing. But how much CPU and memory should it be allowed to use? Without constraints, a single memory-leaking application could destabilize an entire cluster. In the next lesson, "Configure resource requests and limits for Pods to ensure cluster stability and efficient resource usage," we will tackle this critical aspect of resource management.