Implementing Gray (Canary) Release with Spring Cloud Gateway, Nacos and Ribbon
This article explains the concept of gray (canary) release, details the required Spring Boot, Spring Cloud and Nacos versions, describes core components such as Nacos, Spring Cloud Gateway, Ribbon and OpenFeign, and provides a complete code‑first implementation with filters, interceptors, custom load‑balancer rules and deployment instructions for demonstrating gray release scenarios.
Gray release, also known as canary release, is a gradual deployment technique that allows a subset of users to use a new version (B) while the rest continue with the current version (A); if no issues are observed, the new version is rolled out to all users.
The demo project uses Spring Boot 2.3.12.RELEASE, Spring Cloud Hoxton.SR12 and Spring Cloud Alibaba 2.2.9.RELEASE. The core components are Nacos (service registry and configuration center), Spring Cloud Gateway (API gateway), Ribbon (load balancer) and OpenFeign (RPC client).
Gray release is achieved by storing a version metadata in Nacos and using a GrayFlagRequestHolder (ThreadLocal) to carry the gray flag per request. A pre‑filter in the gateway decides whether the request should be routed to the gray version based on a custom header, IP list, city list or user list, and sets the flag in GrayFlagRequestHolder . A post‑filter and a global exception handler clear the ThreadLocal to avoid memory leaks.
Custom Ribbon load‑balancer rules ( AbstractGrayLoadBalancerRule and GrayRoundRobinRule ) read the flag from GrayFlagRequestHolder and filter the service instances according to the required version (ALL, PROD, GRAY). Spring MVC and Feign interceptors propagate the gray flag to downstream calls.
Configuration classes ( GrayGatewayProperties , GrayVersionProperties , GrayAutoConfiguration ) expose properties such as the gray switch, header key/value, IP and city white‑lists, and the production/gray version numbers. The demo starts five services (gateway, user‑app V1/V2, order‑app V1/V2) with different ports and Nacos metadata versions to illustrate the behavior.
Three demonstration scenarios are provided: (1) gray switch off – requests are routed to any version; (2) gray switch on with no matching criteria – only the production version (V1) is used; (3) gray switch on with matching header/IP/city – requests are routed to the gray version (V2). The article also discusses handling gray release for distributed tasks and MQ, and points to the full source code repository.
Java Architect Essentials
Committed to sharing quality articles and tutorials to help Java programmers progress from junior to mid-level to senior architect. We curate high-quality learning resources, interview questions, videos, and projects from across the internet to help you systematically improve your Java architecture skills. Follow and reply '1024' to get Java programming resources. Learn together, grow together.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.