Mesh Routing Rules

Dubbo Mesh routing rules are based on Istio’s VirtualService and DestinationRule modifications. The overall idea and format can refer to Istio’s traffic control rules reference manual: Istio VirtualService and Istio DestinationRule

This article describes the design principles of Dubbo Mesh routing rules, as well as the differences between them and Istio rules. Reference link: https://www.yuque.com/docs/share/c132d5db-0dcb-487f-8833-7c7732964bd4?#.

Basic Idea

Based on the routing chain, the Pipeline processing method is adopted, as shown in the figure below:

route-rule1.png

The logic of the routing chain can be simply understood as target = rn(…r3(r2(r1(src)))). For the internal logic of each router, it can be abstracted as the input address addrs-in and the n mutually exclusive address pools addrs-pool-1 … addrs-pool-n that are split according to the full address addrs-all in the router. The intersection is taken as the output addrs-out according to the rules defined by the implementation. By analogy, the calculation of the entire routing chain is completed.

route-rule2.png

On the other hand, if router(n) needs to execute fallback logic, then after passing through router(n), the fallback logic should be determined.

Fallback Handling Principles

Due to multiple conditional components between multiple routers, it is easy for the address to be filtered out. In this case, we need to perform fallback handling to ensure that the business can smoothly find a valid address under the premise of correctness.

First, let’s look at the following rule

  1. apiVersion: service.dubbo.apache.org/v1alpha1
  2. kind: VirtualService
  3. metadata:
  4.   name: demo-route
  5. spec:
  6.   hosts:
  7.   - demo
  8.   dubbo:
  9.   - service:
  10.     - exact: com.taobao.hsf.demoService:1.0.0
  11.     - exact: com.taobao.hsf.demoService:2.0.0
  12.     routedetail:
  13.     - name: sayHello-String-method-route
  14.       match:
  15.       - method:
  16.           name_match:
  17.             exact: "sayHello"
  18.             .....
  19.           argp:
  20.           - string
  21.       route:
  22.       - destination:
  23.           host: demo
  24.           subset: v1
  25.         fallback:
  26.           destination:
  27.             host: demo
  28.             subset: v2
  29.           fallback:
  30.             destination:
  31.               host: demo
  32.               subset: v3
  34.       - name: sayHello-method-route
  35.         match:
  36.         - method:
  37.             name_match:
  38.               exact: "s-method"
  39.         route:
  40.         - destination:
  41.             host: demo
  42.             subset: v2
  43.           fallback:
  44.             destination:
  45.               host: demo
  46.               subset: v3
  48.       - name: interface-route
  49.         route:
  50.         - destination:
  51.           host: demo
  52.           subset: v3
  54.   - service:
  56.       ....
  57. ---
  58. apiVersion: service.dubbo.apache.org/v1alpha1
  59. kind: DestinationRule
  60. metadata:
  61.   name: demo-route
  62. spec:
  63.   host: demo
  64.   subsets:
  65.   - name: v1
  66.     labels:
  67.       sigma.ali/mg: v1-host
  69.   - name: v2
  70.     labels:
  71.       sigma.ali/mg: v2-host
  73.   - name: v3
  74.     labels:
  75.       sigma.ali/mg: v3-host

Taking script routing as an example, the matching condition of this script routing follows a principle, which is that the matching range is a process from precise to broad. In this example, it is a matching search process from the sayHello(string) parameter -> sayHello method -> interface-level routing.

So if we have met a certain condition but the selected subset address is empty, how do we perform fallback handling?

Taking the matching sayHello(string) parameter condition as an example, we select the v1 subset. If it is empty, we can look for the address at the next level, which is to look for the address at the method level. The specific configuration is as follows

  1.        - name: sayHello-String-method-route
  2.          match:
  3.           - method:
  4.              name_match:
  5.                exact: "sayHello"
  6.                .....
  7.              argp:
  8.               - string
  9.          route:
  10.           - destination:
  11.               host: demo
  12.               subset: v1
  13.             fallback:
  14.               destination:
  15.                 host: demo
  16.                 subset: v2
  17.               fallback:
  18.                 destination:
  19.                   host: demo
  20.                   subset: v3

At this time, the address we selected is the v2 method-level address. If v2 still has no address, according to the definition of the rule, we can fallback to the v3 interface level.

Suppose we have a method match, if there is no address, we need not to perform fallback and directly report an error. We can configure it like this

  1. apiVersion: service.dubbo.apache.org/v1alpha1
  2. kind: VirtualService
  3. metadata:
  4.   name: demo-route
  5. spec:
  6.   hosts:
  7.   - demo
  8.   dubbo:
  9.   - service:
  10.     - exact: com.taobao.hsf.demoService:1.0.0
  11.     - exact: com.taobao.hsf.demoService:2.0.0
  12.     routedetail:
  13.       - name: sayHello-String-method-route
  14.         match:
  15.         - method:
  16.             name_match:
  17.               exact: "sayHello"
  18.               .....
  19.             argp:
  20.             - string
  21.         route:
  22.         - destination:
  23.             host: demo
  24.             subset: v1
  25.           fallback:
  26.             destination:
  27.               host: demo
  28.               subset: v2
  29.             fallback:
  30.               destination:
  31.                 host: demo
  32.                 subset: v3
  34.       - name: sayHello-method-route
  35.         match:
  36.         - method:
  37.             name_match:
  38.               exact: "s-method"
  39.         route:
  40.         - destination:
  41.             host: demo
  42.             subset: v2
  43.           fallback:
  44.             destination:
  45.               host: demo
  46.               subset: v3
  47.       - name: some-method-route
  48.         match:
  49.         - method:
  50.             name_match:
  51.               exact: "some-method"
  52.         route:
  53.         - destination:
  54.             host: demo
  55.             subset: v4
  57.       - name: interface-route
  58.         route:
  59.         - destination:
  60.           host: demo
  61.           subset: v3
  63.   - service:
  65.       ....
  66. ---
  67. apiVersion: service.dubbo.apache.org/v1alpha1
  68. kind: DestinationRule
  69. metadata:
  70.   name: demo-route
  71. spec:
  72.   host: demo
  73.   subsets:
  74.   - name: v1
  75.     labels:
  76.       sigma.ali/mg: v1-host
  78.   - name: v2
  79.     labels:
  80.       sigma.ali/mg: v2-host
  82.   - name: v3
  83.     labels:
  84.       sigma.ali/mg: v3-host

From this rule, we can see that when matching the some-method condition, the corresponding v4 subset is selected. When v4 is empty, because there is no fallback configured, an error will be reported directly.

Summary of Fallback Handling Principles

  • We should configure the fallback handling logic of the Destination in the VirtualService route.
  • When falling back to a subset, if the corresponding subset is also configured with a fallback subset, it should also be handled recursively; the relationship between fallback subsets should also be from specific to broad.
  • When writing matching conditions, we should follow the principle of from specific conditions to broad conditions.

RouteChain Assembly Mode (Not yet implemented)

route-rule3.png

As we can see in the above figure, in the routing process, we use the Pipeline processing method. The Router nodes in the Pipeline are sequential, and each Router has a unique corresponding VirtualService and multiple corresponding DestinationRules for description.

Taking the routing rule configuration stored in Nacos as an example, the configuration format is as follows:

  1. DataId: Demo.rule.yaml
  2. GROUP: HSF
  4. content:
  6. VirtualService A
  7. ---
  8. DestinationRule A1
  9. ---
  10. DestinationRule A2
  11. ---
  12. VirtualService B
  13. ---
  14. DestinationRule B
  15. ---
  16. VirtualService C
  17. ---
  18. DestinationRule C
  19. ---
  20. ...

VirtualService A and DestinationRule A1, DestinationRule A2 form a Router A, VirtualService B and DestinationRule B form Router B, and so on, completing the assembly of the entire router chain.

Example: Proportional Traffic Routing Rules

Note, although the following rules are very similar to Istio’s VirtualService and DestinationRule, there are some differences in the working process and specific rules compared to Istio. Dubbo only references Istio’s design. If you want to integrate with the native Istio service mesh governance system, please refer to Integrating Service Mesh Traffic Governance.

In some scenarios, we need to distribute traffic with the same attributes proportionally to different instance groups. A typical example scenario is A/B testing, where we need to forward 20% of the traffic to the new version v2 of the service to verify the stability of the new version, or to direct a portion of internal company users to the new version v2 for testing and verification. Another application scenario is to achieve canary releases of services, gradually adjusting the traffic distribution ratio so that the new version’s traffic gradually increases and eventually fully migrates all traffic to the new version.

Example of Proportional Traffic Rules

The following example will proportionally forward all requests to the getDetail method of the service org.apache.dubbo.demo.DetailService.

  1. ...
  2. apiVersion: service.dubbo.apache.org/v1alpha1
  3. kind: VirtualService
  4. metadata:
  5.   name: details
  6. spec:
  7.   dubbo:
  8.    - name: detail-service-traffic-split
  9.      match:
  10.       - name:
  11.         services:
  12.          - exact: "org.apache.dubbo.demo.DetailService"
  13.         method:
  14.          name_match:
  15.           exact: "getDetail"
  16.      route:
  17.       - destination:
  18.          subset: details-v1
  19.         weight: 60
  20.       - destination:
  21.          subset: details-v2
  22.         weight: 40
  23. ---
  24. ...
  25. apiVersion: service.dubbo.apache.org/v1alpha1
  26. kind: DestinationRule
  27. metadata:
  28.   name: reviews-route
  29. spec:
  30.   subsets:
  31.     - name: details-v1
  32.       labels:
  33.         detail_version: v1 # 'version' is a reserved key in Dubbo, so must not be used.
  34.     - name: details-v2
  35.       labels:
  36.         detail_version: v2 # 'version' is a reserved key in Dubbo, so must not be used.
  37. ---
Dubbo VirtualService

This part can fully refer to the semantics of Istio VirtualService, as they are almost identical. Dubbo adds the dubbo protocol label (corresponding to the http protocol position) and enriches the match conditions.

The match condition sets the traffic rule to be effective only for requests to the getDetail method of the service “org.apache.dubbo.demo.DetailService”.

  1. match:
  2.   - name:
  3.     services:
  4.      - exact: "org.apache.dubbo.demo.DetailService"
  5.     method:
  6.      name_match:
  7.       exact: "getDetail"

The following route specifies the target instance subsets for the matched traffic. The instance subsets details-v1 and details-v2 are defined through the DestinationRule below. For unmatched traffic, it can access any instance by default without any filtering.

  1. route:
  2.   - destination:
  3.      subset: details-v1
  4.     weight: 60
  5.   - destination:
  6.      subset: details-v2
  7.     weight: 40
Dubbo DestinationRule

This part can fully refer to the semantics of Istio DestinationRule, as they are identical.

The following rule divides the application details into two deployment versions v1 and v2 by matching the detail_version value, named details-v1 and details-v2 respectively. At the same time, details-v1 and details-v2 will become the traffic forwarding target objects of Dubbo VirtualService.

  1. subsets:
  2.  - name: details-v1
  3.    labels:
  4.      detail_version: v1 # 'version' is a reserved key in Dubbo, so must not be used.
  5.  - name: details-v2
  6.    labels:
  7.      detail_version: v2 # 'version' is a reserved key in Dubbo, so must not be used.

Similar to label routing, this involves how to label your instances (here it is detail_version). Please refer to the section How to Label Instances below.

In addition to the functions introduced above that are very similar to Istio’s traffic rules, Dubbo’s VirtualService and DestinationRule can also achieve things that Istio rules cannot, such as method parameter routing. For details, see the Reference Manual.

Feedback

Was this page helpful?

Yes No

Last modified September 30, 2024: Update & Translate Overview Docs (#3040) (d37ebceaea7)