Achieving Zero‑Downtime Deployments with Spring Cloud on Kubernetes

Background and Goal

The series "Best Practices for Spring Cloud on Kubernetes" reaches its eighth part, focusing on achieving lossless traffic during service start‑up and shutdown. Maintaining SLA during deployments requires a systematic approach to graceful up‑ and down‑scaling.

What Is Graceful Up‑Scaling?

Analogous to completing a house before occupants move in, a service should become fully initialized before it starts receiving traffic. Prematurely opening sockets or initializing dependent resources (database, message queue, Redis) can cause long client waits or runtime errors.

What Is Graceful Down‑Scaling?

Similar to evacuating a building before demolition, a service must stop accepting new requests, finish in‑flight requests, clean up resources, and then exit. This process must also handle unexpected failures such as database disconnections.

Design Principles for Graceful Down‑Scaling

Components should form a hierarchical structure.

Worker threads must receive a stop signal and exit gracefully, or be daemon threads.

Construction should follow a bottom‑up dependency order.

Destruction should follow a top‑down order, mirroring the build process.

Implementation Path

The graceful shutdown process consists of four key steps:

Receive Signal : Handle external termination signals (e.g., SIGTERM) rather than relying on internal crashes.

Stop Accepting Traffic : Allow in‑flight requests to finish while refusing new ones; for background tasks, stop consuming new messages.

Destroy Resources : Clean up caches, locks, thread pools, and any blocking I/O before the main thread exits.

Spring Cloud Application Mechanics

Spring Cloud applications consist of the core boot application and a set of starters. Key concepts include:

Starter : Auto‑configuration modules loaded by Spring Boot.

Bean : All components are beans managed by the container.

Context : Bean container that publishes lifecycle events.

LifeCycle : Interface for managing component lifecycles.

ApplicationEvent : Event‑based communication between modules and the container.

Leveraging these native events enables graceful handling of the entire lifecycle.

1. Graceful Up‑Scaling in Spring Cloud

Spring Cloud emits several lifecycle events during startup (e.g., ApplicationReadyEvent, CommandLineRunner). By configuring beans that react to these events, services can defer registration with service registries until they are fully ready.

2. Graceful Down‑Scaling in Spring Cloud

Spring Boot 2.3+ provides built‑in graceful shutdown for web applications. Add the following properties to application.properties:

server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=20s

The shutdown sequence works as follows:

Close the listening socket and wait for ongoing requests to finish (implemented by WebServerGracefulShutdownLifecycle).

Trigger the web container shutdown (via WebServerStartStopLifecycle).

For versions prior to 2.3, custom shutdown hooks or health‑state changes can be used, as described in the referenced GitHub discussions.

Scenario‑Based Implementations

Scenario 1: Direct Web Service Access

Complete processing of in‑flight requests.

Safely shut down the application.

Clients observe a connection reset after the graceful window.

Configuration example (Spring Boot 2.3+):

server.shutdown=graceful
spring.lifecycle.timeout-per-shutdown-phase=20s

Scenario 2: Behind a Reverse Proxy

Ensure the proxy stops routing traffic to the instance after health checks report unhealthy.

Mark the instance unhealthy, wait for the proxy to deregister it, then shut down.

For pre‑2.3 versions, replace the default shutdown hook and manipulate health status manually.

Scenario 3: Microservice Cluster

Beyond completing Scenario 1 tasks, the service must deregister from the service registry. Two approaches are suggested:

Execute a script or listen to ContextClosedEvent to remove the instance from the registry, then wait for load‑balancer refresh.

Enable client‑side retry (e.g., Spring‑retry) to handle connection failures during the transition.

Kubernetes Mechanisms

Kubernetes provides lifecycle hooks and health probes. When a pod receives SIGTERM, a preStop script can run, for example:

lifecycle:
  preStop:
    exec:
      command:
        - sh
        - -c
        - "sleep 5"

This delay allows the service control plane to finish deregistration before the container terminates.

Kubernetes also distinguishes between Liveness and Readiness probes:

/actuator/health/liveness

/actuator/health/readiness

Spring Boot automatically exposes these endpoints, enabling Kubernetes to stop routing traffic when readiness fails while still allowing the container to be recreated if liveness fails.

Integration of Spring Cloud and Kubernetes

By publishing a LivenessState.BROKEN event, a Spring Cloud application running in Kubernetes can trigger graceful shutdown without additional code.

Additional Built‑In Capabilities (EDAS)

Alibaba Cloud's EDAS offers out‑of‑the‑box, no‑code solutions for lossless shutdown of Spring Cloud and Dubbo services, as well as isolation of unhealthy instances. The references are provided as technical documentation links.

Next Steps

The article concludes the deployment series and hints at upcoming high‑availability topics, such as handling traffic spikes and avoiding resource waste after peak periods.