higress

title: Frontend Gray keywords: [higress, frontend gray] description: Frontend Gray Plugin Configuration Reference ## Feature Description The frontend-gray plugin implements frontend user grayscale capabilities. This plugin can be used for business A/B testing while ensuring system release stability through grayscale, monitoring, and rollback strategies. ## Runtime Properties Execution Stage: Default Stage
Execution Priority: 1000 ## Configuration Fields | Name | Data Type | Required | Default | Description | |------|-----------|----------|---------|-------------| | grayKey | string | Optional | - | Unique user identifier from Cookie/Header (e.g., userid). If empty, uses rules[].grayTagKey and rules[].grayTagValue to filter rules. | | localStorageGrayKey | string | Optional | - | When using JWT authentication, user ID comes from localStorage. Overrides grayKey if configured. | | graySubKey | string | Optional | - | Used when user info is in JSON format (e.g., userInfo:{ userCode:"001" }). In this example, graySubKey would be userCode. | | storeMaxAge | int | Optional | 31536000 | Max cookie storage duration in seconds (default: 1 year). | | indexPaths | string[] | Optional | - | Paths requiring mandatory processing (supports Glob patterns). Example: /resource/**/manifest-main.json in micro-frontend scenarios. | | skippedPaths | string[] | Optional | - | Excluded paths (supports Glob patterns). Example: /api/** XHR requests in rewrite scenarios. | | skippedByHeaders | map<string, string> | Optional | - | Filter requests via headers. skippedPaths has higher priority. HTML page requests are unaffected. | | rules | object[] | Required | - | User-defined grayscale rules for different scenarios. | | rewrite | object | Required | - | Rewrite configuration for OSS/CDN deployments. | | baseDeployment | object | Optional | - | Baseline configuration. | | grayDeployments | object[] | Optional | - | Gray deployment rules and versions. | | backendGrayTag | string | Optional | x-mse-tag | Backend grayscale tag. Cookies will carry ${backendGrayTag}:${grayDeployments[].backendVersion} if configured. | | uniqueGrayTag | string | Optional | x-higress-uid | UUID stored in cookies for percentage-based grayscale session stickiness and backend tracking. | | injection | object | Optional | - | Inject global info into HTML (e.g., <script>window.global = {...}</script>). | ### rules Field | Name | Data Type | Required | Default | Description | |------|-----------|----------|---------|-------------| | name | string | Required | - | Unique rule name linked to grayDeployments[].name. | | grayKeyValue | string[] | Optional | - | User ID whitelist. | | grayTagKey | string | Optional | - | User tag key from cookies. | | grayTagValue | string[] | Optional | - | User tag values from cookies. | ### rewrite Field > Both indexRouting and fileRouting use prefix matching. The {version} placeholder will be dynamically replaced by baseDeployment.version or grayDeployments[].version. | Name | Data Type | Required | Default | Description | |------|-----------|----------|---------|-------------| | host | string | Optional | - | Host address (use VPC endpoint for OSS). | | indexRouting | map<string, string> | Optional | - | Homepage rewrite rules. Key: route path, Value: target file. Example: /app1 → /mfe/app1/{version}/index.html. | | fileRouting | map<string, string> | Optional | - | Resource rewrite rules. Key: resource path, Value: target path. Example: /app1/ → /mfe/app1/{version}. | ### baseDeployment Field | Name | Data Type | Required | Default | Description | |------|-----------|----------|---------|-------------| | version | string | Required | - | Baseline version as fallback. | | backendVersion | string | Required | - | Backend grayscale version written to cookies via ${backendGrayTag}. | | versionPredicates | string | Required | - | Supports multi-version mapping for micro-frontend scenarios. | ### grayDeployments Field | Name | Data Type | Required | Default | Description | |------|-----------|----------|---------|-------------| | version | string | Required | - | Gray version used when rules match. Adds x-higress-tag header for non-CDN deployments. | | versionPredicates | string | Required | - | Multi-version support for micro-frontends. | | backendVersion | string | Required | - | Backend grayscale version for cookies. | | name | string | Required | - | Linked to rules[].name. | | enabled | boolean | Required | - | Enable/disable rule. | | weight | int | Optional | - | Traffic percentage (e.g., 50). | > Percentage-based Grayscale Notes: > 1. Percentage rules override user-based rules when both exist. > 2. Uses UUID fingerprint hashed via SHA-256 for traffic distribution. ### injection Field | Name | Data Type | Required | Default | Description | |------|-----------|----------|---------|-------------| | globalConfig | object | Optional | - | Global variables injected into HTML. | | head | string[] | Optional | - | Inject elements into <head>. | | body | object | Optional | - | Inject elements into <body>. | #### globalConfig Sub-field | Name | Data Type | Required | Default | Description | |------|-----------|----------|---------|-------------| | key | string | Optional | HIGRESS_CONSOLE_CONFIG | Window global variable key. | | featureKey | string | Optional | FEATURE_STATUS | Rule hit status (e.g., {"beta-user":true}). | | value | string | Optional | - | Custom global value. | | enabled | boolean | Optional | false | Enable global injection. | #### body Sub-field | Name | Data Type | Required | Default | Description | |------|-----------|----------|---------|-------------| | first | string[] | Optional | - | Inject at body start. | | after | string[] | Optional | - | Inject at body end. | ## Configuration Examples ### Basic Configuration (User-based) ```yml 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