Implementing Version-Based Routing and Gray Deployment for Microservices

1. Background

In distributed systems, multiple development teams may work on the same service, resulting in parallel versions during development. To keep versions isolated, requests must be routed to the specific version for acceptance testing, enabling gray‑deployment strategies.

2. Load Strategy

When services have multiple versioned clusters, traditional round‑robin, weight, or random strategies are insufficient. Custom routing rules are needed, often using request headers, cookies, or parameters to match and direct traffic to the appropriate version.

Default master branch routing

Requests typically run on the main branch; if custom rules don’t match, the master service acts as a fallback. The master’s health indicates overall service health.

Version‑based routing

Requests carrying a version tag (e.g.,

2.0.0

) are routed to the matching service version; otherwise, the master handles the request.

Service‑specific routing

Individual services can be directed to specific branches, e.g., service B to

1.0.0

and service C to

3.0.0

, while others use the main branch. After matching a versioned cluster, standard load‑balancing selects an instance.

3. Gray Deployment

When custom load‑balancing respects routing rules, new versions can be released without affecting existing services. Requests are split according to rules, allowing acceptance testing before fully replacing the old version.

Only selected sub‑services are deployed in gray mode, isolated from the main line. Specific configurations enable traffic to flow to gray services.

Process details

Configure routing so default requests go to the main branch.

Deploy new versions without handling requests initially.

During acceptance, route designated requests to the gray layer.

Common rules: version tag, gray user group, percentage split, IP.

After acceptance, promote gray services to the main branch.

Retire the old main services to complete the rollout.

If acceptance fails, rollback or adjust the gray layer.

Gray deployment relies on custom routing and weighted load‑balancing, managed via a configuration center that can be adjusted dynamically during testing.

4. Practical Solution

1. Process Design

Clients carry routing identifiers; if a rule fails to match, the main branch handles the request. Core switch identifiers are centrally managed in the configuration center.

2. Routing Identifier

Identifier acquisition

Typically, routing identifiers are passed in request headers, e.g.:

Version‑based routing:

routeId:2.0.0

– all requests prefer the 2.0.0 branch.

Service‑specific routing:

serverC:3.0.0

– requests to service C use the 3.0.0 branch.

Gateways or interceptors can extract these headers to apply routing rules.

Identifier management

Custom routing requires writing the identifier into a context container during request filtering, then reading it during routing to apply configuration‑based rules.

Write phase: capture routing identifier in filter/interceptor and store in context.

Read phase: retrieve identifier from context during routing and execute rule.

If no identifier is present, the request defaults to the main service.

3. Service Selection

Selecting a service instance involves querying the registry for available services, matching them against routing identifiers, and then applying load‑balancing to pick an instance.

Query the service registry for available instances.

Match instances against routing rules.

Apply load‑balancing to the filtered list.

By embedding version tags into service metadata and combining them with service names or IPs, multi‑dimensional filtering supports most lightweight gray‑deployment strategies.

5. Reference Source Code

应用仓库：
https://gitee.com/cicadasmile/butte-flyer-parent

组件封装：
https://gitee.com/cicadasmile/butte-frame-parent