Mastering Graceful Shutdown and Gray Release with Spring Cloud and Eureka

Introduction

In production environments, guaranteeing that service upgrades do not disrupt user experience is essential. A graceful shutdown aims to take a service offline without interrupting users, providing a “no‑perception” upgrade experience.

Graceful Shutdown

Common shutdown methods

Method 1: kill PID – Directly killing the Java process is simple but not graceful because other services may still see the instance as alive for up to 90 seconds when using Eureka.

Method 2: /shutdown endpoint – Spring Boot exposes an /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 (e.g., via curl -X POST http://host:port/actuator/shutdown) to trigger a graceful stop.

Method 3: /pause endpoint – Spring Boot also provides a /pause actuator. Enable it together with /restart:

management:
  endpoint:
    # enable pause endpoint
    pause:
      enabled: true
    # pause depends on restart
    restart:
      enabled: true
  endpoints:
    web:
      exposure:
        include: pause,restart

POST to /actuator/pause marks the instance as DOWN in Eureka while the application continues to run, allowing traffic to drain before the actual kill.

Method 4: /service-registry endpoint – Expose the /service-registry actuator to set the instance status to DOWN:

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

POST to /actuator/service-registry?status=DOWN updates the registry status. The effect is shown in the following image:

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.";
    }
}

Gray Release (Canary Deployment)

Blue‑Green Deployment

Deploy two identical clusters but serve traffic from only one. When upgrading, switch traffic to the idle cluster, allowing the other to be updated without downtime.

Rolling Update

Update a subset of instances in a single cluster gradually (e.g., 4 out of 12 nodes at a time) until all nodes run the new version. This saves resources compared to blue‑green but lacks a clear “known‑good” environment and can be harder to roll back.

Canary Deployment

Deploy a small percentage of traffic to a new version (the “canary”) while the majority continues using the stable version. Monitor the canary; if successful, gradually increase its traffic share. This approach often works together with A/B testing.