Graceful Shutdown and Gray Release Strategies with Spring Cloud and Eureka

Preface

In production environments, ensuring that service upgrades do not affect user experience is crucial; an elegant shutdown means the service remains available to users without interruption.

Graceful Shutdown

Common Shutdown Methods

Method 1: kill PID

Use kill PID to terminate the Java process. This relies on the Spring Boot Shutdown hook , but when using Eureka the service may remain marked as up for up to 90 seconds, making it less graceful.

Method 2: /shutdown endpoint

Spring Boot provides a /shutdown actuator endpoint. Enable it in application.yml :

management:
  endpoint:
    shutdown:
      enabled: true
  endpoints:
    web:
      exposure:
        include: shutdown

Send a POST request to /actuator/shutdown to stop the application; this works similarly to method 1.

Method 3: /pause endpoint

Spring Boot also offers a /pause actuator endpoint. Enable it with:

management:
  endpoint:
    pause:
      enabled: true
    restart:
      enabled: true
  endpoints:
    web:
      exposure:
        include: pause,restart

POST to /actuator/pause marks the instance as DOWN in Eureka while keeping the process alive, allowing traffic to drain before termination.

Method 4: /service-registry endpoint

Expose the /service-registry endpoint:

management:
  endpoints:
    web:
      exposure:
        include: service-registry

POST to /actuator/service-registry?status=DOWN to deregister the service from Eureka. After traffic drops to zero, the instance can be stopped safely.

Using EurekaAutoServiceRegistration

Programmatically control registration:

@RestController
@RequestMapping("/graceful/registry-service")
public class GracefulOffline {
    @Autowired
    private EurekaAutoServiceRegistration eurekaAutoServiceRegistration;

    @RequestMapping("/online")
    public String online() {
        this.eurekaAutoServiceRegistration.start();
        return "execute online method, online success.";
    }

    @RequestMapping("/offline")
    public String offline() {
        this.eurekaAutoServiceRegistration.stop();
        return "execute offline method, offline success.";
    }
}

These approaches allow a service to be marked DOWN first, wait for traffic to cease, then terminate the process, achieving a relatively elegant shutdown.

Gray Release

Blue‑Green Deployment

Deploy two identical clusters, serve traffic from one, switch to the other for upgrades, then retire the old cluster. This ensures zero‑downtime and low risk.

Rolling Deployment

Update a subset of instances in a single cluster gradually (e.g., 4 out of 12 nodes at a time) until all are upgraded. It saves resources compared to blue‑green but has drawbacks such as lack of a guaranteed “OK” environment and difficulty rolling back.

Canary Deployment

Also known as gray release, it routes a small percentage of users (e.g., 10%) to a new version while the majority stay on the stable version, allowing gradual validation and A/B testing.

Typical steps include preparing artifacts, removing the canary from the load‑balancer, upgrading it, running automated tests, re‑adding it, and then rolling out to the rest of the fleet if successful.