Graceful Shutdown Support in Spring Boot 2.3+ for Embedded Web Servers

Spring Boot 2.3.0.RELEASE introduced graceful shutdown support for all four embedded web servers (Jetty, Reactor Netty, Tomcat, Undertow) for both reactive and servlet‑based applications.

Graceful shutdown is performed during the closing of the application context by the earliest SmartLifecycle beans. A timeout defines a grace period during which existing requests may finish while new requests are rejected (network layer for Jetty, Reactor Netty, Tomcat; HTTP 503 for Undertow).

To enable it, add the following configuration to application.yml (or application.properties ):

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

The shutdown process relies on Java shutdown hooks. Spring Boot registers a shutdown hook that invokes doClose() on the application context, which in turn triggers the LifecycleProcessor to stop all Lifecycle beans.

During web‑server creation, Spring Boot registers a bean that implements SmartLifecycle (e.g., WebServerGracefulShutdownLifecycle ). Its stop(Runnable callback) method calls the embedded server’s shutDownGracefully(...) method.

For Tomcat, the TomcatWebServer holds a GracefulShutdown instance that is invoked only when the shutdown mode is set to GRACEFUL . Other servers have analogous implementations.

The DefaultLifecycleProcessor groups Lifecycle beans by their Phase value, sorts the groups in descending order, and stops each bean. For SmartLifecycle beans the processor uses a CountDownLatch with a timeout (default 30 seconds, configurable via timeout-per-shutdown-phase ) to wait for asynchronous stop callbacks.

In summary, Spring Boot’s graceful shutdown works by:

Registering a JVM shutdown hook that calls doClose() .

Creating a SmartLifecycle bean for the embedded server.

Executing all Lifecycle beans’ stop methods in phase order, with the web‑server bean having the highest priority.

Waiting for asynchronous stop operations to finish within the configured timeout before proceeding to the next phase.