From d0da26bf799eb97712732086fcbc18c4a98dbfb3 Mon Sep 17 00:00:00 2001 From: Dave Syer Date: Thu, 22 Jan 2026 09:08:35 +0000 Subject: [PATCH] Highlight the importance of the preStop hook Graceful shutdown is not sufficient on its own to ensure that in-flight requests are handled during pod termination. The preStop hook should be used to provide sufficient time for in-flight requests. Signed-off-by: Dave Syer See gh-48936 --- .../docs/antora/modules/how-to/pages/deployment/cloud.adoc | 2 ++ .../antora/modules/reference/pages/actuator/endpoints.adoc | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/how-to/pages/deployment/cloud.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/how-to/pages/deployment/cloud.adoc index 102dec7843a..1f9379fb2d4 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/how-to/pages/deployment/cloud.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/how-to/pages/deployment/cloud.adoc @@ -124,6 +124,8 @@ Because this shutdown processing happens in parallel (and due to the nature of d You can configure a sleep execution in a preStop handler to avoid requests being routed to a pod that has already begun shutting down. This sleep should be long enough for new requests to stop being routed to the pod and its duration will vary from deployment to deployment. +The delay should be at least as long as the longest time it takes to process an in-flight request. +You should not rely on the Spring Boot graceful shutdown period alone, as the platform will not be getting any liveness data in the period that the app is shutting down. If you're using Kubernetes 1.32 or up, the preStop handler can be configured by using the PodSpec in the pod's configuration file as follows: diff --git a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/endpoints.adoc b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/endpoints.adoc index c7dfd5f14a1..012f5e567cc 100644 --- a/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/endpoints.adoc +++ b/spring-boot-project/spring-boot-docs/src/docs/antora/modules/reference/pages/actuator/endpoints.adoc @@ -1085,7 +1085,7 @@ When a Spring Boot application shuts down: |`CORRECT` |`REFUSING_TRAFFIC` |New requests are rejected -|If enabled, xref:web/graceful-shutdown.adoc[graceful shutdown processes in-flight requests]. +|If enabled, xref:web/graceful-shutdown.adoc[graceful shutdown processes in-flight requests]. HTTP probes also stop accepting traffic, so the availability states are not readily available externally. |Shutdown complete |N/A @@ -1094,7 +1094,7 @@ When a Spring Boot application shuts down: |The application context is closed and the application is shut down. |=== -TIP: See xref:how-to:deployment/cloud.adoc#howto.deployment.cloud.kubernetes.container-lifecycle[] for more information about Kubernetes deployment. +TIP: See xref:how-to:deployment/cloud.adoc#howto.deployment.cloud.kubernetes.container-lifecycle[] for more information about Kubernetes deployment. In particular, it describes how to use the `preStop` hook to give your application time to shut down gracefully before Kubernetes kills it.