frontend-gray plug-in-API Gateway(API Gateway)-阿里云帮助中心

The frontend-gray plugin enables canary releases for frontend users, supporting A/B Tests and release stability through grayscale, monitoring, and rollback policies.

Running attributes

Plugin execution phase: Authentication phase. Plugin execution priority: 1000.

Fields

Name	Data type	Requirements	Default value	Description
`grayKey`	string	Optional	-	The unique identifier for a user, obtained from a cookie or request header (for example, `userid`). If not specified, the system uses `rules[].grayTagKey` and `rules[].grayTagValue` to match canary release rules.
`useManifestAsEntry`	boolean	Optional	`false`	Whether to use a manifest file as the application entry. Set this to `true` for micro-frontend architectures, where different versions of frontend resources are loaded based on the manifest file content.
`localStorageGrayKey`	string	Optional	-	The unique user identifier from `localStorage` for JSON Web Token (JWT) authentication. If configured, `grayKey` is ignored.
`graySubKey`	string	Optional	-	User identity information may be in JSON format. For example, `userInfo:{ userCode:"001" }`. In this case, set `graySubKey` to `userCode` to extract the identifier.
`storeMaxAge`	int	Optional	`60 * 60 * 24 * 365`	The maximum storage duration for the cookie set by the gateway, in seconds. The default value is one year.
`cookieDomain`	string	Optional	-	The domain for the cookie. Use this to share cookies across subdomains. For example, ".example.com".
`indexPaths`	array of strings	Optional	-	Paths that are always processed by the plug-in. `Glob` patterns are supported. For example, in a micro-frontend scenario, an XHR request to `/resource/**/manifest-main.json` must be routed through the plug-in.
`skippedPaths`	array of strings	Optional	-	Paths to exclude from processing by this plug-in. `Glob` patterns are supported. For example, in a rewrite scenario, an XHR request to `/api/**` may produce unexpected results if processed by the plug-in.
`skippedByHeaders`	map of string to string	Optional	-	Excludes requests from processing based on header values. `skippedPaths` takes priority over this configuration. HTML page requests are not affected.
`rules`	array of object	Required	-	Canary release rules that match users to deployment versions.
`rewrite`	object	Optional	-	The rewrite configuration, typically used for Object Storage Service (OSS) and CDN front ends.
`baseDeployment`	object	Optional	-	The baseline rule configuration.
`grayDeployments`	array of object	Optional	-	Activation rules and target versions for canary releases.
`backendGrayTag`	string	Optional	`x-mse-tag`	The tag for the backend canary release version. If configured, a cookie is set with the value `${backendGrayTag}:${grayDeployments[].backendVersion}`.
`uniqueGrayTag`	string	Optional	`x-higress-uid`	When percentage-based canary release is enabled, the gateway generates a unique identifier and stores it in a `cookie` for session affinity. The backend can also use this value for end-to-end canary release tracing.
`injection`	object	Optional	-	Injects global information into the home page HTML. For example, `<script>window.global = {...}</script>`.

The following table describes the fields in rules.

Name	Data type	Requirements	Default value	Description
`name`	string	Required	-	A unique name for the rule. This is associated with `grayDeployments[].name`.
`grayKeyValue`	array of string	Optional	-	An allowlist of user IDs for this rule.
`grayTagKey`	string	Optional	-	The tag key used to categorize users, obtained from cookies.
`grayTagValue`	array of string	Optional	-	The tag value used to categorize users, obtained from cookies.

The following table describes the fields in rewrite.

Both indexRouting (home page rewrite) and fileRouting (file rewrite) use prefix matching. For example, /app1: /mfe/app1/{version}/index.html means requests with the `/app1` prefix are routed to /mfe/app1/{version}/index.html. {version} is a placeholder dynamically replaced with baseDeployment.version or grayDeployments[].version at runtime.

{version} is a reserved word dynamically replaced with the frontend version from baseDeployment.version or grayDeployments[].version.

Name	Data type	Requirements	Default value	Description
`host`	string	Optional	-	The host address. For OSS, use a VPC endpoint.
`indexRouting`	map of string to string	Optional	-	Defines the routing rule to rewrite the homepage. Each key is a route path for the homepage, and the value is the target file for redirection. For example, the key `/app1` corresponds to the value `/mfe/app1/{version}/index.html`. If the active version is `0.0.1` and the access path is `/app1`, the request is redirected to `/mfe/app1/0.0.1/index.html`.
`fileRouting`	map of string to string	Optional	-	Defines the routing rule to rewrite resource files. Each key is an access path for a resource, and the value is the target file for redirection. For example, the key `/app1/` corresponds to the value `/mfe/app1/{version}`. If the active version is `0.0.1` and the access path is `/app1/js/a.js`, the request is redirected to `/mfe/app1/0.0.1/js/a.js`.

The following table describes the fields in baseDeployment.

Name	Data type	Requirements	Default value	Description
`version`	string	Required	-	The baseline version.
`backendVersion`	string	Optional	-	The backend canary release version, which is written to a cookie with the `key` set to `${backendGrayTag}`.
`versionPredicates`	string	Optional	-	Similar to `version` but supports multiple versions, mapping different versions based on routes. Typically used in micro-frontend scenarios where a main application manages multiple micro-applications.

The following table describes the fields in grayDeployments.

Name	Data type	Requirements	Default value	Description
`version`	string	Required	-	The version number of the canary release. This version is used when the canary release rule matches. For non-CDN deployments, the `x-higress-tag` header is added.
`versionPredicates`	string	Optional	-	Similar to `version` but supports multiple versions, mapping different versions based on routes. Typically used in micro-frontend scenarios where a main application manages multiple micro-applications.
`backendVersion`	string	Optional	-	The backend canary release version. The `x-mse-tag` header is added to `XHR/Fetch` requests sent to the backend.
`name`	string	Required	-	The name of the rule. This is associated with `rules[].name`.
`enabled`	boolean	Optional	-	Whether to enable this rule.
`weight`	int	Optional	-	The percentage of traffic routed to the canary release version. For example, 50.

Configuration examples

Basic configuration (canary release by user)

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

The unique user identifier in the cookie is userid. The current canary release rule is named beta-user.

If the following conditions are met, the version: gray version is used. Otherwise, the version: base version is used.

The userid in the cookie is 00000002 or 00000003.
The level in the cookie is level3 or level5.

Grayscale by percentage

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

The total weight across all canary release rules is 100%. In this example, the canary release version has a weight of 80%, and the baseline version has a weight of 20%.

Store user information in 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

The cookie contains appInfo data in JSON format. The userId field is the unique identifier. The current canary release rule is named beta-user. If the following conditions are met, the version: gray version is used. Otherwise, the version: base version is used.

The userid in the cookie is 00000002 or 00000003.
The level in the cookie is level3 or level5.

User information in LocalStorage

The gateway plugin requires a unique user identifier. Because HTTP can only transfer this in a header, if user information is stored in LocalStorage, inject a script into the home page to copy it to a cookie.

(function() {
	var grayKey = '@@X_GRAY_KEY';
	var cookies = document.cookie.split('; ').filter(function(row) {
		return row.indexOf(grayKey + '=') === 0;
	});

	try {
		if (typeof localStorage !== 'undefined' && localStorage !== null) {
			var storageValue = localStorage.getItem(grayKey);
			var cookieValue = cookies.length > 0 ? decodeURIComponent(cookies[0].split('=')[1]) : null;
			if (storageValue && storageValue.indexOf('=') < 0 && cookieValue !== storageValue) {
				document.cookie = grayKey + '=' + encodeURIComponent(storageValue) + '; path=/;';
				window.location.reload();
			}
		}
	} catch (error) {
		//
	}
})();

Rewrite configuration

This is typically used in CDN deployment scenarios. {version} is dynamically replaced with the actual version at runtime.

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

indexRouting: home page rewriting

Requests to /app1, /app123, /app1/index.html, /app1/xxx, and /xxxx are all routed to /mfe/app1/{version}/index.html.

fileRouting: File routing configuration

The following file mappings are active.

/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

Inject code into the HTML home page

grayKey: userid
rules:
- name: inner-user
  grayKeyValue:
  - '00000001'
  - '00000005'
baseDeployment:
  version: base
grayDeployments:
  - name: beta-user
    version: gray
    enabled: true
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>

The injection field injects code into the HTML home page: into the head tag, or at the first and last positions within the body tag.