Configure the traffic-tag plug-in - Microservices Engine

This topic describes the configuration items of the traffic-tag plug-in. The configurations are used to manage traffic tags that are defined for canary release and test purposes based on specific rules.

Plug-in type

Throttling plug-in.

Description

You can use the traffic-tag plug-in to tag request traffic based on weight or specific request content by adding specific request headers. You can use the traffic-tag plug-in to configure complex-logic rules for tagging traffic.

Configuration items

Field name	Data type	Default value	Required	Description
`conditionGroups`	array of object	-	No	The content-based condition groups. For more information, see the conditionGroups configurations section in this topic.
`weightGroups`	array of object	-	No	The weight-based condition groups. For more information, see the weightGroups configurations section in this topic.
`defaultTagKey`	string	-	No	The default tag key. If no condition is matched, the default tag key is used. This field takes effect only if the defaultTagVal field is configured.
`defaultTagVal`	string	-	No	The default tag value. If no condition is matched, the default tag value is used. This field takes effect only if the defaultTagKey field is configured.

conditionGroups configurations

The following table describes the fields in the conditionGroups configuration item.

Field name	Data type	Default value	Required	Description
`headerName`	string	-	Yes	The name of the HTTP header that you want to add or modify.
`headerValue`	string	-	Yes	The value of the HTTP header.
`logic`	string	-	Yes	The logical relationship among conditions, which can be `and` or `or`. The value must be in lowercase.
`conditions`	array of object	-	Yes	The tagging conditions.

The following table describes the fields in the conditions configuration item.

Field name	Data type	Default value	Required	Description
`conditionType`	string	-	Yes	The condition type, which can be `header`, `parameter`, or `cookie`.
`key`	string	-	Yes	The condition keyword.
`operator`	string	-	Yes	The operator, which can be `equal`, `not_equal`, `prefix`, `in`, `not_in`, `regex`, or `percentage`.
`value`	array of string	-	Yes	The condition value. You can configure multiple values only if the operator is `in` or `not_in`.

Note

If the operator is regex, the regular expression engine RE2 is used. For more information, see RE2 official documentation.

weightGroups configurations

The following table describes the fields in the weightGroups configuration item.

Field name	Data type	Default value	Required	Description
`headerName`	string	-	Yes	The name of the HTTP header that you want to add or modify.
`headerValue`	string	-	Yes	The value of the HTTP header.
`weight`	integer	-	Yes	The traffic weight in percentage.

Operators

Operator	Description
`equal`	If a value is exactly the same as the specified value, a condition is met.
`not_equal`	If a value differs from the specified value, a condition is met.
`prefix`	If a value is prefixed with the specified value, a condition is met.
`in`	If a value is included in the specified list, a condition is met.
`not_in`	If a value is excluded from the specified list, a condition is met.
`regex`	If a value complies with the regular expression rules, a condition is met.
`percentage`	If the inequality `hash(get(key)) % 100 < value` is true, a condition is true.

Note

The percentage operator and weight field differ in the following aspects:

percentage operator: used in a conditional expression to determine whether to perform an operation based on a specified percentage and key-value pair. For a key-value pair, the results of multiple matches are idempotent. If a condition is hit, the condition will be hit in subsequent matches.
weight field: used to define the weight for routing traffic to different paths. If traffic is tagged based on weight, the weight field determines the percentage of traffic that is routed to a path. Unlike the percentage operator, the weight field does not define a fixed comparison basis, and traffic is randomly distributed based on weight. A request may be routed to different paths in different matches.
If you use the percentage operator, the system determines whether a request meets specified percentage conditions. If you use the weight field, the system distributes traffic in a static and random manner.

Configuration examples

Enable the traffic-tag plug-in for specific routes

In this example, route-a and route-b specified in _match_route_ are the route names configured for the created gateway routes. If one of the two routes is matched, the configurations take effect.

If multiple rules are configured, the rules take effect in the order specified in _rules_. If a rule is matched, configurations of the rule take effect, and subsequent rules are ignored.

Example 1: Content-based matching

In the following sample code, requests that are routed to the route-a and route-b routes are matched. If the header role of a request is user, viewer, or editor and foo=bar is specified in the request, the request header x-mse-tag: gray is added to the request. If no condition is matched for a request, the request header x-mse-tag: base is added to the request, as defined in the configurations of the defaultTagKey and defaultTagVal fields.

# Use the _rules_ field to configure fine-grained rules.
_rules_:
- _match_route_:
  - route-a
  - route-b
  defaultTagKey: x-mse-tag
  defaultTagVal: base
  conditionGroups:
    - headerName: x-mse-tag
      headerValue: gray
      logic: and
      conditions:
        - conditionType: header
          key: role
          operator: in
          value:
            - user
            - viewer
            - editor
        - conditionType: parameter
          key: foo
          operator: equal
          value:
          - bar

Example 2: Weight-based matching

In the following sample code, a request has a 30% chance of being added with the request header x-mse-tag: gray, another 30% chance of being added with the request header x-mse-tag: blue, and a 40% chance of being added with no request header.

_rules_:
- _match_route_:
  - route-a
  - route-b
  # The total weight is 100. The weight value 40, which is not configured, indicates that no header is added.
  weightGroups:
    - headerName: x-mse-tag
      headerValue: gray
      weight: 30
    - headerName: x-mse-tag
      headerValue: blue
      weight: 30

Enable the traffic-tag plug-in for specific domain names

In this example, *.example.com and test.com specified in _match_domain_ are the domain names used to match requests. If one of the two domain names is matched, the configurations take effect.

In the following sample code, requests that access *.example.com or test.com are matched. If a request contains the request header role and the value of the header is prefixed with user, such as role: user_common, the request header x-mse-tag: blue is added to the request.

_rules_:
- _match_domain_:
  - "*.example.com"
  - test.com
  conditionGroups:
    - headerName: x-mse-tag
      headerValue: blue
      logic: and
      conditions:
        - conditionType: header
          key: role
          operator: prefix
          value:
            - user

Enable the traffic-tag plug-in for gateways

In this example, the _rules_ field is not specified and configurations take effect at the gateway level.

You can configure conditionGroups for content-based matching or weightGroups for weight-based matching. If you configure both configuration items, the traffic-tag plug-in preferentially matches requests based on conditions in conditionGroups. If conditions are met, request headers are added, and the matching ends. If no condition in conditionGroups is met, the traffic-tag plug-in adds request headers based on the weight specified in weightGroups.

conditionGroups:
  - headerName: x-mse-tag-1
    headerValue: gray
    # logic is set to or, which indicates that a request is matched if one of the conditions is met.
    logic: or
    conditions:
      - conditionType: header
        key: foo
        operator: equal
        value:
          - bar
      - conditionType: cookie
        key: x-user-type
        operator: prefix
        value:
          - test
  - headerName: x-mse-tag-2
    headerValue: blue
    # logic is set to and, which indicates that a request is matched only if all conditions are met.
    logic: and
    conditions:
      - conditionType: header
        key: x-type
        operator: in
        value:
          - type1
          - type2
          - type3
      - conditionType: header
        key: x-mod
        operator: regex
        value:
          - "^[a-zA-Z0-9]{8}$"
  - headerName: x-mse-tag-3
    headerValue: green
    logic: and
    conditions:
      - conditionType: header
        key: user_id
        operator: percentage
        value:
          - 60
# The total weight is 100. The weight value 40, which is not configured, indicates that no header is added.
weightGroups:
  - headerName: x-mse-tag
    headerValue: gray
    weight: 30
  - headerName: x-mse-tag
    headerValue: base
    weight: 30