Configuring Spring Boot for Zero-Downtime Deployments Using Load Balancers and Health Checks

Configuring Spring Boot for Zero-Downtime Deployments Using Load Balancers and Health Checks

Introduction

Zero-downtime deployment is a critical objective in modern software delivery, ensuring that application updates and maintenance activities occur without interrupting ongoing service availability. For production-grade applications, even brief downtime can degrade user experience, affect revenue, or cause cascading failures in dependent systems.

Spring Boot applications, widely used for building microservices and web services, must be configured carefully to support zero downtime. By default, application startup and shutdown are straightforward but can cause temporary unavailability or dropped requests during deployments.

This article focuses on how to configure Spring Boot applications (version 2.6.x and above) for zero-downtime deployments by combining graceful shutdown, health checks exposed via Spring Boot Actuator, and integration with load balancers. The aim is to orchestrate deployments where load balancers stop routing traffic to instances that are shutting down while allowing new instances to fully initialize before receiving requests.


1. Understanding the Problem: Downtime During Spring Boot Application Updates

Typical deployment scenarios for Spring Boot applications can lead to downtime due to the nature of server lifecycle events:

  • Instance shutdown typically terminates open connections immediately, causing in-flight requests to fail.
  • Startup sequences may involve initialization logic before the application is ready to serve traffic, but load balancers often route traffic immediately.
  • Default Spring Boot shutdown behavior does not delay container termination to wait for active requests to drain.

These issues can cause:

  • Loss or delay of client requests.
  • Errors and timeouts observable by end-users.
  • Uncoordinated traffic routing, leading to perceived service outages.

Achieving zero downtime requires explicit support for graceful shutdown, where the application:

  1. Signals readiness to serve only after fully initialized.
  2. Signals unreadiness during shutdown to allow load balancers to gracefully stop sending new requests.
  3. Waits for all in-flight requests to complete before termination.

Ensuring this requires both application-side setup and alignment with load balancer behavior.


2. Load Balancers and Their Role in Zero-Downtime Deployment

Load balancers distribute client requests across multiple backend instances, enabling fault tolerance and scalability. Key concepts include:

  • Routing algorithms: Round-robin, least connections, IP hash for sticky sessions.
  • Health-based routing: Directing traffic only to backends deemed healthy by periodic health checks.

Load balancers continuously monitor backend health to avoid sending traffic to down or unhealthy nodes. Common load balancers used with Spring Boot include:

  • NGINX: A popular reverse proxy with configurable active/passive health checks.
  • HAProxy: Offers advanced load balancing and health check options.
  • AWS ELB/ALB: Managed cloud load balancers with integrated health checks.

Tradeoffs in Load Balancer Configuration:

  • Aggressive health check timeouts might mark healthy instances as down too quickly.
  • Slow health checks delay routing changes, increasing potential downtime.
  • Incomplete health checks that only detect liveness but not readiness can route traffic prematurely.

Properly integrating load balancer health checks with application readiness states is vital to seamless deployments.


3. Spring Boot Actuator Health Checks and Integration with Load Balancers

The Spring Boot Actuator module exposes various endpoints for monitoring and managing applications, including health indicators.

  • By default, the health endpoint is exposed at /actuator/health.
  • This endpoint can be customized to provide detailed health status and distinguish between different probe types:
  • Liveness probes: Verify the application is running.
  • Readiness probes: Verify the application is ready to accept traffic.
  • Startup probes: Used to verify initial startup readiness (more relevant in Kubernetes).

> While Kubernetes formally defines these probe types, general load balancers benefit primarily from distinguishing readiness from liveness to avoid premature traffic routing.

Enabling and Configuring Health Endpoints

The following YAML configuration snippet example exposes health and info endpoints and always shows health details, which aids load balancers in making routing decisions.

management:
  endpoints:
    web:
      exposure:
        include: health, info
  endpoint:
    health:
      show-details: always
spring:
  main:
    allow-bean-definition-overriding: true

Customizing Readiness and Liveness Probes

Spring Boot 2.3+ supports multiple health groups where you can define separate endpoints for readiness and liveness checks, for example /actuator/health/readiness and /actuator/health/liveness. This allows load balancers to target the correct probe for routing.


4. Implementing Graceful Shutdown in Spring Boot

Default Shutdown Behavior and Its Limitations

By default, Spring Boot triggers an immediate shutdown on application termination. Embedded servers such as Tomcat stop accepting new connections and close existing requests abruptly, which can cause failure for in-flight requests.

Enabling Graceful Shutdown

Since Spring Boot 2.3, a config property enables graceful shutdown:

server.shutdown=graceful

This instructs Spring Boot to:

  • Stop accepting new requests.
  • Wait for active requests to complete before terminating.

Manual Cleanup and Draining In-flight Requests

For finer control, implement an ApplicationListener<ContextClosedEvent> bean that customizes the embedded Tomcat connector to pause new connections and await thread pool termination.

Example Java Bean:

@Bean
public GracefulShutdown gracefulShutdown() {
    return new GracefulShutdown();
}

public class GracefulShutdown implements TomcatConnectorCustomizer, ApplicationListener<ContextClosedEvent> {
    private volatile Connector connector;

    @Override
    public void customize(Connector connector) {
        this.connector = connector;
    }

    @Override
    public void onApplicationEvent(ContextClosedEvent event) {
        this.connector.pause();
        Executor executor = this.connector.getProtocolHandler().getExecutor();
        if (executor instanceof ThreadPoolExecutor) {
            ThreadPoolExecutor threadPoolExecutor = (ThreadPoolExecutor) executor;
            threadPoolExecutor.shutdown();
            try {
                if (!threadPoolExecutor.awaitTermination(30, TimeUnit.SECONDS)) {
                    System.out.println("Tomcat thread pool did not shut down gracefully within 30 seconds. Proceeding with forceful shutdown");
                }
            } catch (InterruptedException ex) {
                Thread.currentThread().interrupt();
            }
        }
    }
}

This allows the application to drain requests before the JVM exits, reducing request loss.


5. Configuring Load Balancer Health Checks to Respect Readiness Probes

To coordinate zero-downtime deployments, load balancers must query Spring Boot's readiness endpoints rather than simplistic liveness checks.

Example: NGINX Active Health Check Configuration

An NGINX server block can be set to forward health check requests to /actuator/health/readiness:

location /health {
    proxy_pass http://spring_boot_upstream/actuator/health/readiness;
    proxy_intercept_errors on;
}

upstream spring_boot_upstream {
    server app-instance-1:8080 max_fails=3 fail_timeout=30s;
    server app-instance-2:8080 max_fails=3 fail_timeout=30s;
}

Here, NGINX:

  • Periodically requests the readiness endpoint.
  • Stops routing traffic to backends that report unready.

Similar configurations apply for HAProxy and cloud load balancers, adjusted to use Spring Boot’s readiness status.


6. Deployment Strategy: Rolling Updates with Load Balancer Coordination

A typical zero-downtime rolling deployment involves:

  1. Launch a new instance of the Spring Boot application.
  2. Wait until the new instance’s readiness probe returns ready.
  3. Add the new instance to the load balancer's pool.
  4. Mark old instances as unready before shutdown.
  5. Stop routing traffic to old instances.
  6. Shut down old instances gracefully, allowing in-flight requests to complete.

This sequence ensures that there is always a sufficient number of ready instances behind the load balancer, minimizing disruption.

Tradeoffs:

  • Faster rolling updates reduce deployment time but risk insufficient capacity if readiness checks are not reliable.
  • Conservative readiness checks increase reliability but prolong rollback or recovery time.

Developers must balance deployment speed against traffic stability according to business needs.


7. Verification and Validation of Zero-Downtime Deployment Setup

Without access to live production traffic data, engineers can validate zero-downtime setups using:

  • Staged or pre-production environments mimicking production load balancer configurations.
  • Simulator tools that generate concurrent requests during deployment cycles.
  • Monitoring Spring Boot actuator endpoints (health, info) and observing log outputs for shutdown grace periods.
  • Conducting scripted rolling updates to verify no failed requests or downtime in metrics.

These approaches allow identification of misconfigurations or probe mismatches that could cause issues.


8. Lessons Learned and Best Practices

  • Differentiate readiness and liveness probes: Readiness probes prevent traffic routing before the app is ready, while liveness probes check if the app is running.
  • Implement graceful shutdown: Ensure in-flight requests are drained appropriately.
  • Tune load balancer health check intervals and thresholds to balance sensitivity and stability.
  • Leverage Spring Boot Actuator features: Available since 2.3 for graceful shutdown and 2.6.x for enhanced health probe configuration.
  • Coordinate deployment orchestration tools with these probes for minimal human error.

For further reference, consult the official Spring Boot documentation on actuator endpoints and embedded server configuration.


Conclusion

Zero-downtime deployment of Spring Boot applications is achievable through a concerted approach combining load balancer integration, health check sophistication, and graceful shutdown implementation.

By exposing dedicated readiness probes via Spring Boot Actuator, configuring load balancers to respect these health checks, and implementing draining logic on shutdown, teams can deploy application changes without service disruption.

Careful attention to probe definitions, load balancer tuning, and deployment orchestration policies enables robust zero-downtime strategies, improving user experience and operational resilience.

Integrating these techniques thoughtfully will position Spring Boot applications to meet the high availability standards demanded by modern production environments.

For more details, see the official Spring Boot Actuator Documentation and the Spring Boot graceful shutdown guide.


*Note: All techniques and code samples presented are based on documented Spring Boot features and configurations as of version 2.6.x and above. No production incident data or proprietary results are included.*