How OpenSergo Enables Unified Traffic Routing for Cloud‑Native Microservices

What Is Traffic Routing?

Traffic routing directs requests that match specific attributes to designated targets and is a key component of traffic governance. By chaining multiple routing rules, a final set of destination addresses is selected from address tables and then a load‑balancing strategy chooses the actual endpoint. Common scenarios include gray releases, canary releases, disaster‑recovery routing, and tag‑based routing.

Why Unified Governance Is Needed

Modern microservice architectures involve many services written in different languages and using different communication protocols. This heterogeneity creates several pain points:

Inconsistent definitions of service‑governance capabilities across enterprises, leading to high communication costs.

Numerous open‑source frameworks (e.g., Spring Cloud, Dubbo, Istio) lack a common standard, making unified configuration impossible.

Developers must understand both the deployment architecture of each framework and the distinct governance concepts, resulting in high cognitive load.

OpenSergo: A Unified Governance Project

Started in January 2022 by Alibaba together with Bilibili, CloudWego and the community, OpenSergo is an open, language‑agnostic project that covers traffic governance, fault tolerance, metadata management, and security. It provides a single configuration/DSL/protocol to define governance rules, supporting Java, Go, Rust and other ecosystems. By using the OpenSergo CRD standard, developers can manage all components of a microservice system without worrying about framework‑specific differences.

Designing Traffic‑Routing Specs

The article focuses on traffic routing and shows how to design a traffic‑routing Spec that follows the OpenSergo standard, then implements it in Spring Cloud Alibaba.

Tag Routing

Tag routing partitions target workloads by label and routes matching traffic to the corresponding subset. By assigning meaningful meanings to tags, various routing scenarios can be realized.

Canary Release

A canary release gradually rolls out a new version to a small user group before full deployment, reducing risk. The recommended K8s steps are:

Create a gray Deployment with the new image and label it.

Configure a tag‑routing rule that matches the canary users.

Validate the canary and increase the traffic share.

If validation succeeds, promote the new version; otherwise roll back or scale the gray Deployment to zero.

Full‑Link Gray

Full‑link gray releases route all traffic of a specific user segment to a gray version while the rest of the traffic goes to the stable version. This can be achieved by combining traffic routing with traffic‑coloring.

Standardizing Traffic‑Routing Rules

OpenSergo defines three core concepts:

VirtualWorkloads : An abstract collection of workloads (e.g., Deployments, StatefulSets, pods, JVM processes, DB instances) classified by shared attributes.

RouterRule : Maps traffic with particular features to the corresponding VirtualWorkload.

RouterChain : Orders multiple RouterRule and VirtualWorkload objects into a pipeline.

VirtualWorkloads Example

apiVersion: traffic.opensergo.io/v1alpha1
kind: VirtualWorkloads
metadata:
  name: tag-rule
spec:
  selector:
    app: my-app
  virtualWorkload:
    - name: my-app-gray
      target: my-app-gray-deployment
      type: deployment
      selector:
        tag: gray

RouterRule Example (Header‑Based Gray)

apiVersion: traffic.opensergo.io/v1alpha1
kind: RouterRule
metadata:
  name: tag-traffic-router-rule
spec:
  selector:
    app: my-app
  http:
    - name: my-traffic-router-http-rule
      rule:
        match:
          header:
            X-User-Id:
              exact: 12345
          uri:
            exact: "/index"
        targets:
          - workloads: my-app-worksloads
            name: gray
      target:
        workloads: my-app-worksloads
        name: base

Tag‑Routing Scenario

To route traffic with header x-user-id: 123 to instances of spring-cloud-a that carry the gray tag, the following CRDs are used:

apiVersion: traffic.opensergo.io/v1alpha1
kind: TrafficRouterRule
metadata:
  name: tag-traffic-router-rule
spec:
  selector:
    app: spring-cloud-a
  http:
    - name: my-traffic-router-http-rule
      rule:
        match:
          headers:
            X-User-Id:
              regex: "^(?!(?:\d{1,2}|100)$)[0-9]\d+$"
          queryParams:
            name:
              exact: xiaoming
          uri:
            prefix: "/"
        targets:
          - workloads: spring-cloud-a-worksloads
            name: gray
      target:
        - workloads: spring-cloud-a-worksloads
          name: base

apiVersion: traffic.opensergo.io/v1alpha1
kind: VirtualWorkloads
metadata:
  name: spring-cloud-a-worksloads
spec:
  selector:
    app: spring-cloud-a
  virtualWorkload:
    - name: gray
      target: spring-cloud-a
      type: deployment
      selector:
        tag: gray
      loadbalance: random
    - name: base
      target: spring-cloud-a
      type: deployment
      selector:
        tag: _base
      loadbalance: random

Canary Release Scenario (10% Traffic to Gray)

apiVersion: traffic.opensergo.io/v1alpha1
kind: TrafficRouterRule
metadata:
  name: tag-traffic-router-rule
spec:
  selector:
    app: spring-cloud-a
  http:
    - name: my-traffic-router-http-rule
      rule:
        targets:
          - workloads: spring-cloud-a-worksloads
            name: gray
            weight: 10
          - workloads: spring-cloud-a-worksloads
            name: base
            weight: 90
      target:
        - workloads: spring-cloud-a-worksloads
          name: base

Demo Steps

Add the OpenSergo dependency to a Spring Cloud Alibaba consumer application:

<dependency>
    <groupId>com.alibaba.cloud</groupId>
    <artifactId>opensergo-resource-transform</artifactId>
    <version>2.2.9-SNAPSHOT</version>
</dependency>

Start the OpenSergo control plane.

Apply the TrafficRouterRule and VirtualWorkloads CRDs.

Verify results with curl commands:

Default request:

curl http://127.0.0.1:18083/router-test

Returns the v1 instance (metadata.version=v1).

Canary request:

curl -H 'name:xiaoming' http://127.0.0.1:18083/router-test?location=shenzhen

Returns the v2 instance (metadata.version=v2) because the request matches the configured header and query‑parameter conditions.

Conclusion and Outlook

Traffic routing is a crucial part of microservice traffic governance. OpenSergo provides a standardized, multi‑language way to define and apply routing rules, reducing the complexity of managing heterogeneous environments. The project also collaborates with communities such as CloudWeGo, Kratos, Spring Cloud Alibaba, Dubbo, and ShardingSphere to evolve the governance standards and best practices.