Skip to content

docs(frontend-gray): 修改文档配置字段的必填说明和关联说明 #610

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 30, 2025
Merged

docs(frontend-gray): 修改文档配置字段的必填说明和关联说明 #610

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
47772c7
docs(frontend-gray): 修改文档配置字段的必填说明和关联说明
Oct 24, 2025
c3205d2
Merge branch 'main' into fix-frontend-gray-spec
Erica177 Oct 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions backend/sdk/src/main/resources/plugins/frontend-gray/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,15 @@ description: 前端灰度插件配置参考
| `grayKey` | string | 非必填 | - | 用户ID的唯一标识，可以来自Cookie或者Header中，比如 userid，如果没有填写则使用`rules[].grayTagKey`和`rules[].grayTagValue`过滤灰度规则 |
| `graySubKey` | string | 非必填 | - | 用户身份信息可能以JSON形式透出，比如：`userInfo:{ userCode:"001" }`,当前例子`graySubKey`取值为`userCode` |
| `rules` | array of object | 必填 | - | 用户定义不同的灰度规则，适配不同的灰度场景 |
| `rewrite` | object | 必填 | - | 重写配置，一般用于OSS/CDN前端部署的重写配置 |
| `rewrite` | object | 非必填 | - | 重写配置，一般用于OSS/CDN前端部署的重写配置 |
| `baseDeployment` | object | 非必填 | - | 配置Base基线规则的配置 |
| `grayDeployments` | array of object | 非必填 | - | 配置Gray灰度的生效规则，以及生效版本 |

`rules`字段配置说明：

| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
|----------------|--------------|------|-----|-----------------------------------------------------------------------------------|
| `name` | string | 必填 | - | 规则名称唯一标识，和`deploy.gray[].name`进行关联生效 |
| `name` | string | 必填 | - | 规则名称唯一标识，和`grayDeployments[].name`进行关联生效 |
| `grayKeyValue` | array of string | 非必填 | - | 用户ID 白名单列表 |
| `grayTagKey` | string | 非必填 | - | 用户分类打标的标签key值，来自Cookie |
| `grayTagValue` | array of string | 非必填 | - | 用户分类打标的标签value值，来自Cookie |
Expand Down Expand Up @@ -56,9 +56,9 @@ description: 前端灰度插件配置参考
| 名称 | 数据类型 | 填写要求 | 默认值 | 描述 |
|--------|--------|------|-----|-------------------------------------------------|
| `version` | string | 必填 | - | Gray版本的版本号，如果命中灰度规则，则使用此版本。如果是非CDN部署，在header添加`x-higress-tag` |
| `backendVersion` | string | 必填 | - | 后端灰度版本，会在`XHR/Fetch`请求的header头添加 `x-mse-tag`到后端 |
| `backendVersion` | string | 非必填 | - | 后端灰度版本，会在`XHR/Fetch`请求的header头添加 `x-mse-tag`到后端 |
| `name` | string | 必填 | - | 规则名称和`rules[].name`关联， |
| `enabled` | boolean | 必填 | - | 是否启动当前灰度规则 |
| `enabled` | boolean | 非必填 | - | 是否启动当前灰度规则 |

## 配置示例
### 基础配置
Expand Down
8 changes: 4 additions & 4 deletions backend/sdk/src/main/resources/plugins/frontend-gray/README_EN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,14 @@ Plugin execution priority: `450`
| `grayKey` | string | Optional | - | 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. |
| `graySubKey` | string | Optional | - | User identity information may be output in JSON format, for example: `userInfo:{ userCode:"001" }`, in the current example, `graySubKey` is `userCode`. |
| `rules` | array of object | Required | - | User-defined different gray release rules, adapted to different gray release scenarios. |
| `rewrite` | object | Required | - | Rewrite configuration, generally used for OSS/CDN frontend deployment rewrite configurations. |
| `rewrite` | object | Optional | - | Rewrite configuration, generally used for OSS/CDN frontend deployment rewrite configurations. |
| `baseDeployment`| object | Optional | - | Configuration of the Base baseline rules. |
| `grayDeployments` | array of object | Optional | - | Configuration of the effective rules for gray release, as well as the effective versions. |

`rules` field configuration description:
| Name | Data Type | Requirements | Default Value | Description |
|------------------|-------------------|---------------|---------------|--------------------------------------------------------------------------------------------|
| `name` | string | Required | - | Unique identifier for the rule name, associated with `deploy.gray[].name` for effectiveness. |
| `name` | string | Required | - | Unique identifier for the rule name, associated with `grayDeployments[].name` for effectiveness. |
| `grayKeyValue` | array of string | Optional | - | Whitelist of user IDs. |
| `grayTagKey` | string | Optional | - | Label key for user classification tagging, derived from Cookie. |
| `grayTagValue` | array of string | Optional | - | Label value for user classification tagging, derived from Cookie. |
Expand All @@ -48,9 +48,9 @@ Plugin execution priority: `450`
| Name | Data Type | Requirements | Default Value | Description |
|------------------|-------------------|---------------|---------------|----------------------------------------------------------------------------------------------|
| `version` | string | Required | - | 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. |
| `backendVersion` | string | Required | - | Gray version for the backend, which will add `x-mse-tag` to the header of `XHR/Fetch` requests. |
| `backendVersion` | string | Optional | - | Gray version for the backend, which will add `x-mse-tag` to the header of `XHR/Fetch` requests. |
| `name` | string | Required | - | Rule name associated with `rules[].name`. |
| `enabled` | boolean | Required | - | Whether to activate the current gray release rule. |
| `enabled` | boolean | Optional | - | Whether to activate the current gray release rule. |

## Configuration Example
### Basic Configuration
Expand Down
22 changes: 8 additions & 14 deletions backend/sdk/src/main/resources/plugins/frontend-gray/spec.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,9 +54,9 @@ spec:
title: 规则名称
x-title-i18n:
en-US: Rule Name
description: 规则名称唯一标识，和`deploy.gray[].name`进行关联生效
description: 规则名称唯一标识，和`grayDeployments[].name`进行关联生效
x-description-i18n:
en-US: Unique identifier for the rule name, associated with `deploy.gray[].name` for effectiveness.
en-US: Unique identifier for the rule name, associated with `grayDeployments[].name` for effectiveness.
grayKeyValue:
type: array
title: 用户ID白名单
Expand Down Expand Up @@ -183,9 +183,9 @@ spec:
title: 规则名称
x-title-i18n:
en-US: Rule Name
description: 规则名称和`rules[].name`关联
description: 规则名称和`grayDeployments[].name`关联
x-description-i18n:
en-US: Rule name associated with `rules[].name`.
en-US: Rule name associated with `grayDeployments[].name`.
enabled:
type: boolean
title: 是否启用
Expand All @@ -197,11 +197,8 @@ spec:
required:
- version
- name
- enabled
- backendVersion
required:
- rules
- rewrite
example:
grayKey: userid
rules:
Expand Down Expand Up @@ -259,9 +256,9 @@ spec:
title: 规则名称
x-title-i18n:
en-US: Rule Name
description: 规则名称唯一标识，和`deploy.gray[].name`进行关联生效
description: 规则名称唯一标识，和`grayDeployments[].name`进行关联生效
x-description-i18n:
en-US: Unique identifier for the rule name, associated with `deploy.gray[].name` for effectiveness.
en-US: Unique identifier for the rule name, associated with `grayDeployments[].name` for effectiveness.
grayKeyValue:
type: array
title: 用户ID白名单
Expand Down Expand Up @@ -388,9 +385,9 @@ spec:
title: 规则名称
x-title-i18n:
en-US: Rule Name
description: 规则名称和`rules[].name`关联
description: 规则名称和`grayDeployments[].name`关联
x-description-i18n:
en-US: Rule name associated with `rules[].name`.
en-US: Rule name associated with `grayDeployments[].name`.
enabled:
type: boolean
title: 是否启用
Expand All @@ -402,11 +399,8 @@ spec:
required:
- version
- name
- enabled
- backendVersion
required:
- rules
- rewrite
example:
grayKey: userid
rules:
Expand Down
Loading