如何配置traffic-tag外掛程式 - Microservices Engine

本文介紹traffic-tag外掛程式的配置選項詳細資料，此配置用於管理基於灰階發布和測試目的定義的特定規則的流量標記。

外掛程式類型

流量管控。

功能說明

traffic-tag外掛程式允許根據權重或特定請求內容通過添加特定要求標頭的方式對請求流量進行標記。它支援複雜的邏輯來確定如何根據使用者定義的標準標記流量。

配置欄位

欄位名稱	類型	預設值	是否必填	描述
`conditionGroups`	array of object	-	否	定義基於內容的標記條件組，詳細結構見條件組配置。
`weightGroups`	array of object	-	否	定義基於權重的標記條件組，詳細結構見權重組配置。
`defaultTagKey`	string	-	否	預設的標記鍵名，當未匹配到任何條件時使用。若且唯若同時配置了defaultTagVal時生效。
`defaultTagVal`	string	-	否	預設的標記值，當未匹配到任何條件時使用。若且唯若同時配置了defaultTagKey時生效。

條件組配置

conditionGroups中每一項的配置欄位說明如下：

欄位名稱	類型	預設值	是否必填	描述
`headerName`	string	-	是	要添加或修改的HTTP頭名稱。
`headerValue`	string	-	是	HTTP頭的值。
`logic`	string	-	是	條件組中的邏輯關係，支援`and`、`or`，必須為小寫字母。
`conditions`	array of object	-	是	描述具體的標記條件。

conditions 中每一項的配置欄位說明如下：

欄位名稱	類型	預設值	是否必填	描述
`conditionType`	string	-	是	條件類型，支援`header`、`parameter`、`cookie`。
`key`	string	-	是	條件的關鍵字。
`operator`	string	-	是	操作符，支援`equal`、`not_equal`、`prefix`、`in`、`not_in`、`regex`、`percentage`。
`value`	array of string	-	是	條件的值，僅當操作符為`in` 和`not_in`時支援配置多個值。

說明

當operator為regex時，使用的Regex引擎是RE2，詳情請參見RE2 官方文檔。

權重組配置

weightGroups中每一項的配置欄位說明如下：

欄位名稱	類型	預設值	是否必填	描述
`headerName`	string	-	是	要添加或修改的 HTTP 頭名稱。
`headerValue`	string	-	是	HTTP 頭的值。
`weight`	integer	-	是	流量權重百分比。

操作符說明

操作符	描述
`equal`	精確匹配，值需要完全相等。
`not_equal`	不等匹配，值不相等時滿足條件。
`prefix`	首碼匹配，指定值是實際值的首碼時滿足條件。
`in`	包含匹配，實際值需要在指定的列表中。
`not_in`	排除匹配，實際值不在指定的列表中時滿足條件。
`regex`	Regex匹配，按照Regex規則匹配。
`percentage`	百分比匹配，原理：`hash(get(key)) % 100 < value`成立時滿足條件。

說明

關於percentage和weight的區別如下：

percentage操作符：用於條件運算式中，基於指定的百分比和指定的索引值對來判斷是否執行某個操作。對於一個相同的索引值對，多次匹配的結果是等冪的，即這一次命中條件，下一次也會命中。
weight欄位：用於定義不同處理路徑的流量權重。在基於權重的流量標記中，weight確定了某個路徑應接收的流量比例。與percentage不同的是，由於沒有指定固定的對比依據而是基於隨機權重分布，同一個請求的多次匹配可能匹配多個結果。
使用percentage進行條件匹配時，判斷每個請求是否滿足特定百分比條件，而weight則是靜態隨機分配整體流量的比例。

配置樣本

對特定路由開啟

_match_route_中指定的route-a和route-b即在建立網關路由時填寫的路由名稱，當匹配到這兩個路由時，將使用此段配置。

當配置了多個規則時，配置的匹配生效順序將按照_rules_下規則的排列順序，第一個規則匹配後生效對應配置，後續規則將被忽略。

例1: 基於內容的匹配

按照下例的配置，路由route-a和route-b命中的請求中，同時滿足要求標頭role 的值是user、viewer、editor其中之一且存在查詢參數foo=bar的請求將被添加要求標頭x-mse-tag: gray。由於配置了defaultTagKey和defaultTagVal，當未匹配到任何條件時，請求將被添加要求標頭x-mse-tag: base。

# 使用 _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

例2: 基於權重的匹配

按照下列配置，請求將有30%幾率被添加要求標頭x-mse-tag: gray，30%幾率被添加要求標頭x-mse-tag: blue，40%幾率不添加要求標頭。

_rules_:
- _match_route_:
  - route-a
  - route-b
  # 權重總和為100，下例中未配置的40權重將不添加header
  weightGroups:
    - headerName: x-mse-tag
      headerValue: gray
      weight: 30
    - headerName: x-mse-tag
      headerValue: blue
      weight: 30

對特定網域名稱開啟

_match_domain_中指定的*.example.com和test.com 用於匹配請求的網域名稱，當發現網域名稱匹配時，將使用此段配置。

按照下例配置，對於目標為*.example.com和test.com的請求，當含有要求標頭role且其值以user為首碼，比如role: user_common，請求將被添加要求標頭x-mse-tag: blue。

_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

網關執行個體層級開啟

以下配置未指定_rules_欄位，因此將對網關執行個體層級生效。

可按照基於內容或基於權重的匹配單獨配置conditionGroups或weightGroups，若同時配置，外掛程式將先按照conditionGroups中的配置條件進行匹配，匹配成功添加相應要求標頭後跳過後續邏輯。若所有conditionGroups都未匹配成功，則進入weightGroups按照權重配置添加要求標頭。

conditionGroups:
  - headerName: x-mse-tag-1
    headerValue: gray
    # logic為or，則conditions中任一條件滿足就命中匹配
    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為and，需要conditions中所有條件滿足才命中匹配
    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
# 權重總和為100，下例中未配置的40權重將不添加header
weightGroups:
  - headerName: x-mse-tag
    headerValue: gray
    weight: 30
  - headerName: x-mse-tag
    headerValue: base
    weight: 30