Java: Spring Boot: Graceful Shutdown?

Graceful Shutdown — proper termination of a Spring Boot application: finishing current requests, releasing resources, closing connections.

Simple analogy: Graceful Shutdown is like politely leaving a restaurant: you wait for the waiter to bring the bill (finish the current request), say goodbye (release the table), and leave. Instead of "throw money on the table and run out." In production, an abrupt shutdown means lost transactions, corrupted data, and confused users who suddenly get 502 errors.

Why it matters in production: In a Kubernetes cluster with rolling deployments, when a pod is terminated, traffic is still being routed to it. Without graceful shutdown, in-flight requests are dropped mid-execution, database transactions may be left open, and downstream services may receive incomplete data. Graceful shutdown ensures every in-flight request completes before the process exits.

Enabling:

1# application.yml
2server:
3  shutdown: graceful
4spring:
5  lifecycle:
6    timeout-per-shutdown-phase: 30s

What happens on SIGTERM:

1. Kubernetes/OS sends SIGTERM.
2. Spring Boot stops accepting new requests (endpoints return 503).
3. Waits for current requests to finish (up to timeout).
4. Calls @PreDestroy methods.
5. Closes DataSource, ExecutorService, and other resources.
6. Terminates the JVM.

Custom shutdown logic:

1@Component
2@Slf4j
3public class ShutdownHandler {
4    private final ExecutorService executorService;
5    private final NotificationService notificationService;
6    private final KafkaTemplate<String, String> kafkaTemplate;
7
8    @PreDestroy
9    public void onShutdown() {
10        log.info("Starting graceful shutdown...");
11
12        // 1. Stop accepting new work
13        executorService.shutdown();
14
15        // 2. Wait for in-flight tasks
16        try {
17            if (!executorService.awaitTermination(15, TimeUnit.SECONDS)) {
18                executorService.shutdownNow();
19                log.warn("Forced shutdown of executor after timeout");
20            }
21        } catch (InterruptedException e) {
22            executorService.shutdownNow();
23            Thread.currentThread().interrupt();
24        }
25
26        // 3. Deregister from service discovery
27        // discoveryClient.deregister();
28
29        // 4. Send shutdown notification
30        notificationService.notifyShutdown();
31
32        log.info("Graceful shutdown complete");
33    }
34}

Kubernetes configuration:

1spec:
2  terminationGracePeriodSeconds: 60  # Time for graceful shutdown
3  containers:
4  - name: app
5    lifecycle:
6      preStop:
7        exec:
8          command: ["/bin/sh", "-c", "sleep 5"]  # Give time to disconnect from Load Balancer

Production pitfalls:

• Setting timeout too low — long-running queries get killed. Monitor P99 request duration and set timeout-per-shutdown-phase higher than your slowest request.
• Forgetting preStop sleep — Kubernetes sends SIGTERM while the load balancer still routes traffic to the pod. The 5-second delay gives the LB time to deregister.
• Connection pools not draining — HikariCP needs explicit close() to return connections. Spring Boot handles this automatically, but custom pools may not.
• No readiness probe — without it, the pod receives traffic before it is fully ready.

Monitoring:

• Log every @PreDestroy method with timestamps to trace shutdown duration.
• Use server.shutdown=immediate in development for fast restarts, graceful in production.
• Track spring.lifecycle.timeout-per-shutdown-phase with Prometheus to detect slow shutdowns.

Without graceful shutdown — current requests are interrupted, transactions are not committed, users see errors, and downstream services may be left in inconsistent states.