Mastering Version‑Based Routing and Gray Deployments for Microservices

Background

In distributed systems, multiple versions of the same service may run concurrently during development. To keep versions isolated and enable acceptance testing, requests must be routed to the appropriate version, supporting gray‑deployment strategies.

Load Strategy

Standard round‑robin, weight, or random load‑balancing cannot satisfy routing needs when services have multiple versioned clusters. Custom routing rules are commonly designed and developed.

Typical scenarios use Header, Cookie, or Parameter to carry routing information and match requests to the target version.

Default Main‑Branch Routing

Requests usually execute on the main branch; if other branch rules do not match, a fallback to the master service occurs. The master service’s health indicates overall service health.

Version‑Specific Routing

When a request carries a version tag such as 2.0.0, the router first matches services of that version; if none match, the request falls back to the master service.

Service‑Specific Routing

Routing can specify different version branches per service, e.g., service B uses 1.0.0, service C uses 3.0.0, while others run on the main branch. After matching a service version, load‑balancing selects an instance if the version is clustered.

Gray Deployment

When custom load‑balancing follows routing 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 microservices is versioned; gray deployment isolates these services online without impacting the main branch. Requests are diverted to gray services only when specific configurations are enabled.

Process Details

Configure routing so default requests go to the main branch.

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

During acceptance, route requests matching rules to the gray layer.

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

After acceptance, promote gray services to the main branch.

Take down the old main services to complete the rollout.

If acceptance fails, rollback or modify the gray layer.

Practical Solution

1. Process Design

Clients carry routing identifiers; if a rule cannot be matched, the request falls back to the main branch. Core switch identifiers are centrally managed in a configuration center.

2. Routing Identifier

Acquisition

Identifiers are typically passed in request headers for easy management.

Version‑specific routing: routeId:2.0.0 – all requests prioritize the 2.0.0 branch.

Service‑specific routing: serverC:3.0.0 – requests to service C prioritize the 3.0.0 branch.

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

Management

Custom routing rules require writing the identifier into a context container during request filtering, then reading it during routing. If the identifier is absent, the main branch handles the request.

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

Read phase: retrieve identifier from context and apply routing logic.

3. Service Selection

Service selection involves querying the registry, matching services against routing identifiers, and applying load‑balancing to pick an instance.

Query the registry for available instances.

Match instances to the routing identifier.

Apply load‑balancing to select one instance.

Custom routing can embed version tags into service metadata and filter by service name or IP, supporting most lightweight gray‑deployment strategies.

Reference Source Code

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

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