How to Implement Version-Based Routing and Gray Deployment in Microservices

1. Background Introduction

In distributed systems, multiple versions of the same service may run in parallel during development. To keep versions isolated, requests must be routed to the specified version for acceptance testing, enabling gray deployment strategies.

Assume three services A, B, and C, where B and C have multiple versions. By routing requests according to predefined rules, version isolation and gray deployment can be achieved.

2. Load Strategy

When forwarding requests between services in a microservice architecture, conventional round‑robin, weight, or random strategies cannot satisfy the needs of multi‑version clusters. Custom routing rules are therefore required.

Typical scenarios involve carrying routing information via Header, Cookie, or Parameter to match the appropriate version.

Default Master Branch Routing

Requests usually execute on the master branch; if other branch rules do not match, the master service acts as a fallback. The master’s health indicates overall service health, and unmatched routing defaults to the master.

Unified Version Routing

Requests carrying a version tag such as

2.0.0

are routed to the corresponding service version; if no match is found, the master handles the request.

Custom Service Routing

Specific services can be directed to particular version branches, e.g., service B to

1.0.0

and service C to

3.0.0

, while others run on the master branch. After matching a versioned service, load‑balancing selects an instance within that version.

3. Gray Deployment

When load‑balancing follows custom rules, gray releases become straightforward: new versions are deployed without affecting existing services, requests are split according to rules, and after acceptance the old version is replaced.

Only a subset of sub‑services is involved in a gray rollout; the main line remains untouched unless specific configuration enables traffic to the gray services.

Process Details

1. Configure routing so that requests default to the main branch.

2. Deploy versioned services; the gray layer does not handle requests by default.

3. During acceptance, route specified requests to the gray layer.

4. Common rules include version tags, gray user groups, percentage splits, IP filters, etc.

5. After acceptance, promote gray services to the main line.

6. Decommission the old main services to complete the rollout.

7. If acceptance fails, rollback or adjust the gray layer.

Gray deployment relies on custom routing rules and load‑balancing weight adjustments, which can be managed in a configuration center and modified dynamically during testing.

In this mode, the gray service’s launch or removal is almost invisible to users; simple flows can be verified by testers, while complex flows may gradually increase traffic before full promotion.

4. Practical Solution

1. Process Design

During gray rollout, the client carries routing identifiers to direct requests to the target service; if no match occurs, the main branch handles the request. Core switch identifiers are centrally managed in a configuration center.

2. Routing Identifier

Identifier Acquisition

Typically, routing identifiers are placed in request headers for easy management. Common formats include:

Unified version routing:

routeId:2.0.0

– all requests prioritize the

2.0.0

branch.

Custom service routing:

serverC:3.0.0

– requests to service C prioritize the

3.0.0

branch.

Headers can be read in gateway filters or service interceptors to obtain routing parameters.

Identifier Management

Custom routing rules require client identifiers. While obtaining the identifier is simple, propagating it to routing logic involves context management:

Write phase: capture the routing identifier in a filter or interceptor and store it in a context container.

Read phase: during routing, retrieve the identifier from the container and apply the configured rule.

If the identifier is absent, the request defaults to the master service.

3. Service Selection

Choosing a service instance in a microservice environment is complex, especially under gray deployment where routing rules modify the selection process.

1. Query the service registry for the list of available instances.

2. Match instances against the routing identifier.

3. Apply load‑balancing to the filtered list to select the final instance.

The overall routing mechanism involves customizing match rules, loading version tags into service metadata, and filtering by service name or IP to support most lightweight gray strategies.

5. Reference Source Code

Application repository:
https://gitee.com/cicadasmile/butte-flyer-parent

Component package:
https://gitee.com/cicadasmile/butte-frame-parent