higress/plugins/wasm-go/extensions/frontend-gray/README.md

title, keywords, description

title	keywords	description
前端灰度	higress frontend gray	前端灰度插件配置参考

功能说明

frontend-gray插件实现了前端用户灰度的的功能，通过此插件，不但可以用于业务A/B实验，同时通过可灰度配合可监控,可回滚策略保证系统发布运维的稳定性。

运行属性

插件执行阶段：认证阶段 插件执行优先级：450

配置字段

名称	数据类型	填写要求	默认值	描述
grayKey	string	非必填	-	用户ID的唯一标识，可以来自Cookie或者Header中，比如 userid，如果没有填写则使用rules[].grayTagKey和rules[].grayTagValue过滤灰度规则
graySubKey	string	非必填	-	用户身份信息可能以JSON形式透出，比如：userInfo:{ userCode:"001" },当前例子graySubKey取值为userCode
userStickyMaxAge	int	非必填	172800	用户粘滞的时长：单位为秒，默认为172800，2天时间
rules	array of object	必填	-	用户定义不同的灰度规则，适配不同的灰度场景
rewrite	object	必填	-	重写配置，一般用于OSS/CDN前端部署的重写配置
baseDeployment	object	非必填	-	配置Base基线规则的配置
grayDeployments	array of object	非必填	-	配置Gray灰度的生效规则，以及生效版本
backendGrayTag	string	非必填	x-mse-tag	后端灰度版本Tag，如果配置了，cookie中将携带值为${backendGrayTag}:${grayDeployments[].backendVersion}
injection	object	非必填	-	往首页HTML中注入全局信息，比如<script>window.global = {...}</script>

rules字段配置说明：

名称	数据类型	填写要求	默认值	描述
name	string	必填	-	规则名称唯一标识，和deploy.gray[].name进行关联生效
grayKeyValue	array of string	非必填	-	用户ID 白名单列表
grayTagKey	string	非必填	-	用户分类打标的标签key值，来自Cookie
grayTagValue	array of string	非必填	-	用户分类打标的标签value值，来自Cookie

rewrite字段配置说明：

indexRouting首页重写和fileRouting文件重写，本质都是前缀匹配，比如/app1: /mfe/app1/{version}/index.html代表/app1为前缀的请求，路由到/mfe/app1/{version}/index.html页面上，其中{version}代表版本号，在运行过程中会被baseDeployment.version或者grayDeployments[].version动态替换。

{version} 作为保留字段，在执行过程中会被baseDeployment.version或者grayDeployments[].version动态替换前端版本。

名称	数据类型	填写要求	默认值	描述
host	string	非必填	-	host地址，如果是OSS则设置为 VPC 内网访问地址
notFoundUri	string	非必填	-	404 页面配置
indexRouting	map of string to string	非必填	-	用于定义首页重写路由规则。每个键 (Key) 表示首页的路由路径，值 (Value) 则指向重定向的目标文件。例如，键为 /app1 对应的值为 /mfe/app1/{version}/index.html。生效version为0.0.1， 访问路径为 /app1，则重定向到 /mfe/app1/0.0.1/index.html。
fileRouting	map of string to string	非必填	-	用于定义资源文件重写路由规则。每个键 (Key) 表示资源访问路径，值 (Value) 则指向重定向的目标文件。例如，键为 /app1/ 对应的值为 /mfe/app1/{version}。生效version为0.0.1，访问路径为 /app1/js/a.js，则重定向到 /mfe/app1/0.0.1/js/a.js。

baseDeployment字段配置说明：

名称	数据类型	填写要求	默认值	描述
version	string	必填	-	Base版本的版本号，作为兜底的版本

grayDeployments字段配置说明：

名称	数据类型	填写要求	默认值	描述
version	string	必填	-	Gray版本的版本号，如果命中灰度规则，则使用此版本。如果是非CDN部署，在header添加x-higress-tag
backendVersion	string	必填	-	后端灰度版本，配合key为${backendGrayTag}，写入cookie中
name	string	必填	-	规则名称和rules[].name关联，
enabled	boolean	必填	-	是否启动当前灰度规则
weight	int	非必填	-	按照比例灰度，比如50。注意：灰度规则权重总和不能超过100，如果同时配置了grayKey以及grayDeployments[0].weight按照比例灰度优先生效

为了实现按比例（weight） 进行灰度发布，并确保用户粘滞，我们需要确认客户端的唯一性。如果配置了 grayKey，则将其用作唯一标识；如果未配置 grayKey，则使用客户端的访问 IP 地址作为唯一标识。

injection字段配置说明：

名称	数据类型	填写要求	默认值	描述
head	array of string	非必填	-	注入head信息，比如<link rel="stylesheet" href="https://cdn.example.com/styles.css">
body	object	非必填	-	注入Body

injection.body字段配置说明：

名称	数据类型	填写要求	默认值	描述
first	array of string	非必填	-	注入body标签的首部
after	array of string	非必填	-	注入body标签的尾部

配置示例

基础配置（按用户灰度）

grayKey: userid
rules:
- name: inner-user
  grayKeyValue:
  - '00000001'
  - '00000005'
- name: beta-user
  grayKeyValue:
  - '00000002'
  - '00000003'
  grayTagKey: level
  grayTagValue:
  - level3
  - level5
baseDeployment:
  version: base
grayDeployments:
  - name: beta-user
    version: gray
    enabled: true

cookie中的用户唯一标识为 userid，当前灰度规则配置了beta-user的规则。

当满足下面调试的时候，会使用version: gray版本

• cookie中userid等于00000002或者00000003
• cookie中level等于level3或者level5的用户

否则使用version: base版本

按比例灰度

grayKey: userid
rules:
- name: inner-user
  grayKeyValue:
  - '00000001'
  - '00000005'
baseDeployment:
  version: base
grayDeployments:
  - name: beta-user
    version: gray
    enabled: true
    weight: 80

总的灰度规则为100%，其中灰度版本的权重为80%，基线版本为20%。一旦用户命中了灰度规则，会根据IP固定这个用户的灰度版本（否则会在下次请求时随机选择一个灰度版本）。

用户信息存在JSON中

grayKey: appInfo
graySubKey: userId
rules:
- name: inner-user
  grayKeyValue:
  - '00000001'
  - '00000005'
- name: beta-user
  grayKeyValue:
  - '00000002'
  - '00000003'
  grayTagKey: level
  grayTagValue:
  - level3
  - level5
baseDeployment:
  version: base
grayDeployments:
  - name: beta-user
    version: gray
    enabled: true

cookie存在appInfo的JSON数据，其中包含userId字段为当前的唯一标识 当前灰度规则配置了beta-user的规则。 当满足下面调试的时候，会使用version: gray版本

• cookie中userid等于00000002或者00000003
• cookie中level等于level3或者level5的用户

否则使用version: base版本

rewrite重写配置

一般用于CDN部署场景

grayKey: userid
rules:
- name: inner-user
  grayKeyValue:
  - '00000001'
  - '00000005'
- name: beta-user
  grayKeyValue:
  - '00000002'
  - '00000003'
  grayTagKey: level
  grayTagValue:
  - level3
  - level5
rewrite:
  host: frontend-gray.oss-cn-shanghai-internal.aliyuncs.com
  notFoundUri: /mfe/app1/dev/404.html
  indexRouting:
    /app1: '/mfe/app1/{version}/index.html'
    /: '/mfe/app1/{version}/index.html',
  fileRouting:
    /: '/mfe/app1/{version}'
    /app1/: '/mfe/app1/{version}'
baseDeployment:
  version: base
grayDeployments:
  - name: beta-user
    version: gray
    enabled: true

{version}会在运行过程中动态替换为真正的版本

indexRouting：首页路由配置

访问 /app1, /app123,/app1/index.html, /app1/xxx, /xxxx 都会路由到'/mfe/app1/{version}/index.html'

fileRouting：文件路由配置

下面文件映射均生效

• /js/a.js => /mfe/app1/v1.0.0/js/a.js
• /js/template/a.js => /mfe/app1/v1.0.0/js/template/a.js
• /app1/js/a.js => /mfe/app1/v1.0.0/js/a.js
• /app1/js/template/a.js => /mfe/app1/v1.0.0/js/template/a.js

往HTML首页注入代码

grayKey: userid
rules:
- name: inner-user
  grayKeyValue:
  - '00000001'
  - '00000005'
baseDeployment:
  version: base
grayDeployments:
  - name: beta-user
    version: gray
    enabled: true
    weight: 80
injection:
  head: 
    - <script>console.log('Header')</script>
  body:
    first:
      - <script>console.log('hello world before')</script>
      - <script>console.log('hello world before1')</script>
    last:
      - <script>console.log('hello world after')</script>
      - <script>console.log('hello world after2')</script>

通过 injection往HTML首页注入代码，可以在head标签注入代码，也可以在body标签的first和last位置注入代码。