moonming commented on a change in pull request #2935: URL: https://github.com/apache/apisix/pull/2935#discussion_r548771731
########## File path: doc/plugins/traffic-split.md ########## @@ -0,0 +1,409 @@ +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +- [中文](../zh-cn/plugins/traffic-split.md) + +# Summary + +- [**Name**](#name) +- [**Attributes**](#attributes) +- [**How To Enable**](#how-to-enable) + - [**Grayscale Release**](#grayscale-release) + - [**Blue-green Release**](#blue-green-release) + - [**Custom Release**](#custom-release) +- [**Disable Plugin**](#disable-plugin) + +## Name + +The traffic split plugin allows users to incrementally direct percentages of traffic between various upstreams. + +Note: Since the selection of different upstream in the plugin is based on the roundrobin algorithm, the ratio of traffic distribution is not completely accurate when the algorithm state is reset. Review comment: Can not understand ########## File path: doc/plugins/traffic-split.md ########## @@ -0,0 +1,409 @@ +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +- [中文](../zh-cn/plugins/traffic-split.md) + +# Summary + +- [**Name**](#name) +- [**Attributes**](#attributes) +- [**How To Enable**](#how-to-enable) + - [**Grayscale Release**](#grayscale-release) + - [**Blue-green Release**](#blue-green-release) + - [**Custom Release**](#custom-release) +- [**Disable Plugin**](#disable-plugin) + +## Name + +The traffic split plugin allows users to incrementally direct percentages of traffic between various upstreams. + +Note: Since the selection of different upstream in the plugin is based on the roundrobin algorithm, the ratio of traffic distribution is not completely accurate when the algorithm state is reset. + +## Attributes + +| Name | Type | Requirement | Default | Valid | Description | +| ---------------- | ------- | ----------- | ------- | ------- | ---------------------------------------------------------------------------------------- | +| rules.match | array[object] | optional | | | List of matching rules. | +| rules.match.vars | array[array] | optional | | | A list consisting of one or more {var, operator, val} elements, like this: {{var, operator, val}, {var, operator, val}, ...}}. For example: {"arg_name", "==", "json"}, which means that the current request parameter name is json. The var here is consistent with the naming of Nginx internal variables, so request_uri, host, etc. can also be used; for the operator part, the currently supported operators are ==, ~=, ~~, >, <, in, has and !. For specific usage of operators, please see the `operator-list` part of [lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list). | +| rules.weighted_upstreams | array[object] | optional | | | List of upstream configuration rules. | +| rules.weighted_upstreams.upstream_id | string or integer | optional | | | The upstream id is bound to the corresponding upstream(not currently supported). | +| rules.weighted_upstreams.upstream | object | optional | | | Upstream configuration information. | +| rules.weighted_upstreams.upstream.type | enum | optional | roundrobin | [roundrobin, chash] | roundrobin supports weighted load, chash consistent hashing, the two are alternatives. | +| rules.weighted_upstreams.upstream.nodes | object | optional | | | In the hash table, the key of the internal element is the list of upstream machine addresses, in the format of address + Port, where the address part can be an IP or a domain name, such as 192.168.1.100:80, foo.com:80, etc. value is the weight of the node. In particular, when the weight value is 0, it has special meaning, which usually means that the upstream node is invalid and never wants to be selected. | +| rules.weighted_upstreams.upstream.timeout | object | optional | 15 | | Set the timeout period for connecting, sending and receiving messages (time unit: second, all default to 15 seconds). | +| rules.weighted_upstreams.upstream.pass_host | enum | optional | "pass" | ["pass", "node", "rewrite"] | pass: pass the host requested by the client, node: pass the host requested by the client; use the host configured with the upstream node, rewrite: rewrite the host with the value configured by the upstream_host. | +| rules.weighted_upstreams.upstream.name | string | optional | | | Identify the upstream service name, usage scenario, etc. | +| rules.weighted_upstreams.upstream.upstream_host | string | optional | | | Only valid when pass_host is configured as rewrite. | +| rules.weighted_upstreams.weight | integer | optional | weight = 1 | | The traffic is divided according to the `weight` value, and the roundrobin algorithm is used to divide multiple `weight`. | + +## How To Enable Review comment: The content is nothing with how to enable ########## File path: doc/zh-cn/plugins/traffic-split.md ########## @@ -0,0 +1,420 @@ +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +- [English](../../plugins/traffic-split.md) + +# 目录 + +- [名字](#名字) +- [属性](#属性) +- [如何启用](#如何启用) + - [灰度发布](#灰度发布) + - [蓝绿发布](#蓝绿发布) + - [自定义发布](#自定义发布) +- [禁用插件](#禁用插件) + +## 名字 + +traffic-split 插件使用户可以逐步引导各个上游之间的流量百分比。 + +注：由于插件中选择不同上游是根据 roundrobin 算法选择，因此存在算法状态重置的情况下，会对流量分配的比率并不完全精准。 + +## 属性 + +| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述 | +| ------------ | ------------- | ------ | ------ | ------ | -------------------- | +| rules.match | array[object] | 可选 | | | 匹配规则列表 | +| rules.match.vars | array[array] | 可选 | | | 由一个或多个{var, operator, val}元素组成的列表，类似这样：{{var, operator, val}, {var, operator, val}, ...}}。例如：{"arg_name", "==", "json"}，表示当前请求参数 name 是 json。这里的 var 与 Nginx 内部自身变量命名是保持一致，所以也可以使用 request_uri、host 等；对于 operator 部分，目前已支持的运算符有 ==、~=、~~、>、<、in、has 和 ! 。操作符的具体用法请看 [lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 的 `operator-list` 部分。 | +| rules.weighted_upstreams | array[object] | 可选 | | | 上游配置规则列表。 | +| rules.weighted_upstreams.upstream_id | string or integer | 可选 | | | 通过上游 id 绑定对应上游(暂不支持)。 | +| rules.weighted_upstreams.upstream | object | 可选 | | | 上游配置信息。 | +| rules.weighted_upstreams.upstream.type | enum | 可选 | roundrobin | [roundrobin, chash] | roundrobin 支持权重的负载，chash 一致性哈希，两者是二选一的(目前只支持 `roundrobin`)。 | +| rules.weighted_upstreams.upstream.nodes | object | 可选 | | | 哈希表，内部元素的 key 是上游机器地址 列表，格式为地址 + Port，其中地址部 分可以是 IP 也可以是域名，⽐如 192.168.1.100:80、foo.com:80等。 value 则是节点的权重，特别的，当权重 值为 0 有特殊含义，通常代表该上游节点 失效，永远不希望被选中。 | +| rules.weighted_upstreams.upstream.timeout | object | 可选 | 15 | | 设置连接、发送消息、接收消息的超时时间(时间单位：秒，都默认为 15 秒)。 | +| rules.weighted_upstreams.upstream.pass_host | enum | 可选 | "pass" | ["pass", "node", "rewrite"] | pass: 透传客户端请求的 host, node: 不透传客户端请求的 host; 使用 upstream node 配置的 host, rewrite: 使用 upstream_host 配置的值重写 host 。 | +| rules.weighted_upstreams.upstream.name | string | 可选 | | | 标识上游服务名称、使⽤场景等。 | +| rules.weighted_upstreams.upstream.upstream_host | string | 可选 | | | 只在 pass_host 配置为 rewrite 时有效。 | +| rules.weighted_upstreams.weight | integer | 可选 | weight = 1 | | 根据 `weight` 值做流量划分，多个 weight 之间使用 roundrobin 算法划分。| + +## 如何启用 + +traffic-split 插件主要由 `match` 和 `weighted_upstreams` 两部分组成，`match` 是自定义的条件规则，`weighted_upstreams` 是 upstream 的信息。在使用插件时，至少需要配置 `weighted_upstreams` 部分，这样将默认 `match` 规则通过，会根据 `weighted_upstreams` 中的 `weight` 值，逐步引导各个 upstream 之间的流量比例。你也可以同时配置 `match` 和 `weighted_upstreams`，这样只有 `match` 规则匹配通过后，才会对 `weighted_upstreams` 中的流量进行划分。 Review comment: The grammar is not clear ########## File path: doc/zh-cn/plugins/traffic-split.md ########## @@ -0,0 +1,420 @@ +<!-- +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +--> + +- [English](../../plugins/traffic-split.md) + +# 目录 + +- [名字](#名字) +- [属性](#属性) +- [如何启用](#如何启用) + - [灰度发布](#灰度发布) + - [蓝绿发布](#蓝绿发布) + - [自定义发布](#自定义发布) +- [禁用插件](#禁用插件) + +## 名字 + +traffic-split 插件使用户可以逐步引导各个上游之间的流量百分比。 + +注：由于插件中选择不同上游是根据 roundrobin 算法选择，因此存在算法状态重置的情况下，会对流量分配的比率并不完全精准。 + +## 属性 + +| 参数名 | 类型 | 可选项 | 默认值 | 有效值 | 描述 | +| ------------ | ------------- | ------ | ------ | ------ | -------------------- | +| rules.match | array[object] | 可选 | | | 匹配规则列表 | +| rules.match.vars | array[array] | 可选 | | | 由一个或多个{var, operator, val}元素组成的列表，类似这样：{{var, operator, val}, {var, operator, val}, ...}}。例如：{"arg_name", "==", "json"}，表示当前请求参数 name 是 json。这里的 var 与 Nginx 内部自身变量命名是保持一致，所以也可以使用 request_uri、host 等；对于 operator 部分，目前已支持的运算符有 ==、~=、~~、>、<、in、has 和 ! 。操作符的具体用法请看 [lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 的 `operator-list` 部分。 | +| rules.weighted_upstreams | array[object] | 可选 | | | 上游配置规则列表。 | +| rules.weighted_upstreams.upstream_id | string or integer | 可选 | | | 通过上游 id 绑定对应上游(暂不支持)。 | +| rules.weighted_upstreams.upstream | object | 可选 | | | 上游配置信息。 | +| rules.weighted_upstreams.upstream.type | enum | 可选 | roundrobin | [roundrobin, chash] | roundrobin 支持权重的负载，chash 一致性哈希，两者是二选一的(目前只支持 `roundrobin`)。 | +| rules.weighted_upstreams.upstream.nodes | object | 可选 | | | 哈希表，内部元素的 key 是上游机器地址 列表，格式为地址 + Port，其中地址部 分可以是 IP 也可以是域名，⽐如 192.168.1.100:80、foo.com:80等。 value 则是节点的权重，特别的，当权重 值为 0 有特殊含义，通常代表该上游节点 失效，永远不希望被选中。 | +| rules.weighted_upstreams.upstream.timeout | object | 可选 | 15 | | 设置连接、发送消息、接收消息的超时时间(时间单位：秒，都默认为 15 秒)。 | +| rules.weighted_upstreams.upstream.pass_host | enum | 可选 | "pass" | ["pass", "node", "rewrite"] | pass: 透传客户端请求的 host, node: 不透传客户端请求的 host; 使用 upstream node 配置的 host, rewrite: 使用 upstream_host 配置的值重写 host 。 | +| rules.weighted_upstreams.upstream.name | string | 可选 | | | 标识上游服务名称、使⽤场景等。 | +| rules.weighted_upstreams.upstream.upstream_host | string | 可选 | | | 只在 pass_host 配置为 rewrite 时有效。 | +| rules.weighted_upstreams.weight | integer | 可选 | weight = 1 | | 根据 `weight` 值做流量划分，多个 weight 之间使用 roundrobin 算法划分。| + +## 如何启用 + +traffic-split 插件主要由 `match` 和 `weighted_upstreams` 两部分组成，`match` 是自定义的条件规则，`weighted_upstreams` 是 upstream 的信息。在使用插件时，至少需要配置 `weighted_upstreams` 部分，这样将默认 `match` 规则通过，会根据 `weighted_upstreams` 中的 `weight` 值，逐步引导各个 upstream 之间的流量比例。你也可以同时配置 `match` 和 `weighted_upstreams`，这样只有 `match` 规则匹配通过后，才会对 `weighted_upstreams` 中的流量进行划分。 + +>注：1、在 `match` 里，vars 中的表达式是 `and` 的关系，多个 `vars` 之间是 `or` 的关系。2、在插件的 weighted_upstreams 中只有 `weight` 值，表示到达默认 `route` 上的 upstream 流量权重值。如： + +```json +{ + "weight": 2 +} +``` + +下面提供插件的使用示例，这将有助于你对插件使用上的理解。 + +### 灰度发布 + +不配置 `match` 规则部分（已经默认 `match` 通过），根据插件中 weighted_upstreams 配置的 `weight` 值做流量分流。将 `插件 upstream` 与 `route 的 upstream` 请求流量按 3:2 进行划分，其中 60% 的流量到达插件中的 `1981` 端口的 upstream， 40% 的流量到达 route 上默认 `1980` 端口的 upstream。 Review comment: ditto ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
