Function Description

The frontend-gray plugin implements the functionality of user gray release on the frontend. Through this plugin, it can be used for business A/B testing, while the gradual release combined with monitorable and rollback strategies ensures the stability of system release operations.

Runtime Attributes

Plugin execution phase: Authentication Phase
Plugin execution priority: 450

Configuration Fields

NameData TypeRequirementsDefault ValueDescription
grayKeystringOptional-The unique identifier of the user ID, which can be from Cookie or Header, such as userid. If not provided, uses rules[].grayTagKey and rules[].grayTagValue to filter gray release rules.
graySubKeystringOptional-User identity information may be output in JSON format, for example: userInfo:{ userCode:”001” }, in the current example, graySubKey is userCode.
rulesarray of objectRequired-User-defined different gray release rules, adapted to different gray release scenarios.
rewriteobjectRequired-Rewrite configuration, generally used for OSS/CDN frontend deployment rewrite configurations.
baseDeploymentobjectOptional-Configuration of the Base baseline rules.
grayDeploymentsarray of objectOptional-Configuration of the effective rules for gray release, as well as the effective versions.

rules field configuration description:

NameData TypeRequirementsDefault ValueDescription
namestringRequired-Unique identifier for the rule name, associated with deploy.gray[].name for effectiveness.
grayKeyValuearray of stringOptional-Whitelist of user IDs.
grayTagKeystringOptional-Label key for user classification tagging, derived from Cookie.
grayTagValuearray of stringOptional-Label value for user classification tagging, derived from Cookie.

rewrite field configuration description:

indexRouting homepage rewrite and fileRouting file rewrite essentially use prefix matching, for example, /app1: /mfe/app1/{version}/index.html represents requests with the prefix /app1 routed to /mfe/app1/{version}/index.html page, where {version} represents the version number, which will be dynamically replaced by baseDeployment.version or grayDeployments[].version during execution.
{version} will be replaced dynamically during execution by the frontend version from baseDeployment.version or grayDeployments[].version.

NameData TypeRequirementsDefault ValueDescription
hoststringOptional-Host address, if OSS set to the VPC internal access address.
notFoundUristringOptional-404 page configuration.
indexRoutingmap of string to stringOptional-Defines the homepage rewrite routing rules. Each key represents the homepage routing path, and the value points to the redirect target file. For example, the key /app1 corresponds to the value /mfe/app1/{version}/index.html. If the effective version is 0.0.1, the access path is /app1, it redirects to /mfe/app1/0.0.1/index.html.
fileRoutingmap of string to stringOptional-Defines resource file rewrite routing rules. Each key represents the resource access path, and the value points to the redirect target file. For example, the key /app1/ corresponds to the value /mfe/app1/{version}. If the effective version is 0.0.1, the access path is /app1/js/a.js, it redirects to /mfe/app1/0.0.1/js/a.js.

baseDeployment field configuration description:

NameData TypeRequirementsDefault ValueDescription
versionstringRequired-The version number of the Base version, as a fallback version.

grayDeployments field configuration description:

NameData TypeRequirementsDefault ValueDescription
versionstringRequired-Version number of the Gray version, if the gray rules are hit, this version will be used. If it is a non-CDN deployment, add x-higress-tag to the header.
backendVersionstringRequired-Gray version for the backend, which will add x-mse-tag to the header of XHR/Fetch requests.
namestringRequired-Rule name associated with rules[].name.
enabledbooleanRequired-Whether to activate the current gray release rule.

Configuration Example

Basic Configuration

  1. grayKey: userid
  2. rules:
  3. - name: inner-user
  4.   grayKeyValue:
  5.   - ‘00000001’
  6.   - ‘00000005’
  7. - name: beta-user
  8.   grayKeyValue:
  9.   - ‘00000002’
  10.   - ‘00000003’
  11.   grayTagKey: level
  12.   grayTagValue:
  13.   - level3
  14.   - level5
  15. baseDeployment:
  16.   version: base
  17. grayDeployments:
  18.   - name: beta-user
  19.     version: gray
  20.     enabled: true

The unique identifier of the user in the cookie is userid, and the current gray release rule has configured the beta-user rule.
When the following conditions are met, the version version: gray will be used:

  • userid in the cookie equals 00000002 or 00000003
  • Users whose level in the cookie equals level3 or level5
    Otherwise, use version version: base.

User Information Exists in JSON

  1. grayKey: appInfo
  2. graySubKey: userId
  3. rules:
  4. - name: inner-user
  5.   grayKeyValue:
  6.   - ‘00000001’
  7.   - ‘00000005’
  8. - name: beta-user
  9.   grayKeyValue:
  10.   - ‘00000002’
  11.   - ‘00000003’
  12.   grayTagKey: level
  13.   grayTagValue:
  14.   - level3
  15.   - level5
  16. baseDeployment:
  17.   version: base
  18. grayDeployments:
  19.   - name: beta-user
  20.     version: gray
  21.     enabled: true

The cookie contains JSON data for appInfo, which includes the field userId as the current unique identifier.
The current gray release rule has configured the beta-user rule.
When the following conditions are met, the version version: gray will be used:

  • userid in the cookie equals 00000002 or 00000003
  • Users whose level in the cookie equals level3 or level5
    Otherwise, use version version: base.

Rewrite Configuration

Generally used in CDN deployment scenarios.

  1. grayKey: userid
  2. rules:
  3. - name: inner-user
  4.   grayKeyValue:
  5.   - ‘00000001’
  6.   - ‘00000005’
  7. - name: beta-user
  8.   grayKeyValue:
  9.   - ‘00000002’
  10.   - ‘00000003’
  11.   grayTagKey: level
  12.   grayTagValue:
  13.   - level3
  14.   - level5
  15. rewrite:
  16.   host: frontend-gray.oss-cn-shanghai-internal.aliyuncs.com
  17.   notFoundUri: /mfe/app1/dev/404.html
  18.   indexRouting:
  19.     /app1: ‘/mfe/app1/{version}/index.html’
  20.     /: ‘/mfe/app1/{version}/index.html’,
  21.   fileRouting:
  22.     /: ‘/mfe/app1/{version}’
  23.     /app1/: ‘/mfe/app1/{version}’
  24. baseDeployment:
  25.   version: base
  26. grayDeployments:
  27.   - name: beta-user
  28.     version: gray
  29.     enabled: true

{version} will be dynamically replaced with the actual version during execution.

indexRouting: Homepage Route Configuration

Accessing /app1, /app123, /app1/index.html, /app1/xxx, /xxxx will route to ‘/mfe/app1/{version}/index.html’.

fileRouting: File Route Configuration

The following file mappings are effective:

  • /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