From fa3cf60ed596ce43b2260e7bda289e99f6207de4 Mon Sep 17 00:00:00 2001 From: tzssangglass Date: Mon, 29 Aug 2022 16:17:13 +0800 Subject: [PATCH 1/5] docs: add docs of workflow plugin --- docs/en/latest/plugins/workflow.md | 150 +++++++++++++++++++++++++++++ docs/zh/latest/plugins/workflow.md | 150 +++++++++++++++++++++++++++++ 2 files changed, 300 insertions(+) create mode 100644 docs/en/latest/plugins/workflow.md create mode 100644 docs/zh/latest/plugins/workflow.md diff --git a/docs/en/latest/plugins/workflow.md b/docs/en/latest/plugins/workflow.md new file mode 100644 index 000000000000..db48e9b54400 --- /dev/null +++ b/docs/en/latest/plugins/workflow.md @@ -0,0 +1,150 @@ +--- +title: workflow +keywords: + - APISIX + - Plugin + - workflow +description: This document contains information about the Apache APISIX workflow Plugin. +--- + + + +## Description + +The `workflow` plugin is used to introduce [lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) to provide complex traffic control features. + +## Attributes + +| Name | Type | Required | Default | Valid values | Description | +| ---------------------------- | ------------- | -------- | ------- | ------------ | ------------------------------------------------------------ | +| rules.case | array[array] | True | | | List of variables to match for filtering requests for conditional traffic split. It is in the format `{variable operator value}`. For example, `{"arg_name", "==", "json"}`. The variables here are consistent with Nginx internal variables. For details on supported operators, [lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list). | +| rules.actions | array[object] | True | | | The action to be performed when the case matches successfully. Currently, only one element is supported in actions. The first child element of the actions' only element can be `return` or `limit-count`. | +| rules.actions[1].return | string | False | | | Return directly to the client. | +| rules.actions[1].[2].code | integer | False | | | HTTP status code returned to the client. | +| rules.actions[1].limit-count | string | False | | | Execute the functions of the `limit-count` plugin. | +| rules.actions[1].[2] | object | False | | | Configuration of `limit-count` plugin, `group` is not supported. | + +:::note + +In `rules`, match `case` in order according to the index of the `rules`, and execute `actions` directly if `case` match. + +::: + +## Enabling the Plugin + +You can configure the `workflow` plugin on a Route as shown below: + +```shell +curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "uri":"/hello/*", + "plugins":{ + "workflow":{ + "rules":[ + { + "case":[ + ["uri", "==", "/hello/rejected"] + ], + "actions":[ + [ + "return", + {"code": 403} + ] + ] + }, + { + "case":[ + ["uri", "==", "/hello/v2/appid"] + ], + "actions":[ + [ + "limit-count", + { + "count":2, + "time_window":60, + "rejected_code":429 + } + ] + ] + } + ] + } + }, + "upstream":{ + "type":"roundrobin", + "nodes":{ + "127.0.0.1:1980":1 + } + } +}' +``` + +Here, the `workflow` Plugin is enabled on the Route. If the request matches the `case` in the `rules`, the `actions` will be executed. + +Example 1: if the request uri is `/hello/rejected`, the `workflow` plugin would return directly to the client + +```shell +curl http://127.0.0.1:9080/hello/rejected -i +HTTP/1.1 403 Forbidden +...... + +{"error_msg":"rejected by workflow"} +``` + +Example 2: if the request uri is `/hello/v2/appid`, the `workflow` plugin would execute the `limit-count` plugin + +```shell +curl http://127.0.0.1:0080/hello/v2/appid -i +HTTP/1.1 200 OK +``` + +```shell +curl http://127.0.0.1:0080/hello/v2/appid -i +HTTP/1.1 200 OK +``` + +```shell +curl http://127.0.0.1:0080/hello/v2/appid -i +HTTP/1.1 429 Too Many Requests +``` + +Example 3: if the request can not match any `case` in the `rules`, the `workflow` plugin would do nothing + +```shell +curl http://127.0.0.1:0080/hello/fake -i +HTTP/1.1 200 OK +``` + +## Disable Plugin + +To disable the `workflow` plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect. + +```shell +curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "uri":"/hello/*", + "upstream": { + "type": "roundrobin", + "nodes": { + "127.0.0.1:1980": 1 + } + } +}' +``` diff --git a/docs/zh/latest/plugins/workflow.md b/docs/zh/latest/plugins/workflow.md new file mode 100644 index 000000000000..2ffd28163ae3 --- /dev/null +++ b/docs/zh/latest/plugins/workflow.md @@ -0,0 +1,150 @@ +--- +title: workflow +keywords: + - APISIX + - Plugin + - workflow +description: 本文介绍了关于 Apache APISIX `workflow` 插件的基本信息及使用方法。 +--- + + + +## 描述 + +`workflow` 插件引入 [lua-resty-expr](https://github.com/api7/lua-resty-expr#operator-list) 来提供复杂的流量控制功能。 + +## 属性 + +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +| ------------- | ------ | ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | +| rules.case | 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.actions | array[object] | 是 | | | 当 `case` 成功匹配时要执行的 `actions`。目前，`actions` 中只支持一个元素。`actions` 的唯一元素的第一个子元素可以是 `return` 或 `limit-count`。 | +| rules.actions[1].return | string | 否 | | | 直接返回到客户端。 | +| rules.actions[1].[2].code | integer | 否 | | | 返回给客户端的 HTTP 状态码。 | +| rules.actions[1].limit-count | string | 否 | | | 执行 `limit-count` 插件的功能。 | +| rules.actions[1].[2] | object | 否 | | | `limit-count` 插件的配置。 | + +:::note + +在 `rules` 中，按照 `rules` 的数组下标顺序依次匹配 `case`，如果 `case` 匹配成功，则直接执行对应的 `actions`。 + +::: + +## 启用插件 + +以下示例展示了如何在路由中启用 `workflow` 插件： + +```shell +curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "uri":"/hello/*", + "plugins":{ + "workflow":{ + "rules":[ + { + "case":[ + ["uri", "==", "/hello/rejected"] + ], + "actions":[ + [ + "return", + {"code": 403} + ] + ] + }, + { + "case":[ + ["uri", "==", "/hello/v2/appid"] + ], + "actions":[ + [ + "limit-count", + { + "count":2, + "time_window":60, + "rejected_code":429 + } + ] + ] + } + ] + } + }, + "upstream":{ + "type":"roundrobin", + "nodes":{ + "127.0.0.1:1980":1 + } + } +}' +``` + +如上，我们启用了 `workflow` 插件，如果请求与 `rules` 中的 `case` 匹配，则会执行对应的 `actions`。 + +示例 1: 如果请求的 uri 是 `/hello/rejected`，则返回给客户端状态码 403。 + +```shell +curl http://127.0.0.1:9080/hello/rejected -i +HTTP/1.1 403 Forbidden +...... + +{"error_msg":"rejected by workflow"} +``` + +示例 2: 如果请求的 uri 是 `/hello/v2/appid`，则执行 `limit-count` 插件，限制请求的数量为 2，时间窗口为 60 秒，如果超过限制数量，则返回给客户端状态码 429 + +```shell +curl http://127.0.0.1:0080/hello/v2/appid -i +HTTP/1.1 200 OK +``` + +```shell +curl http://127.0.0.1:0080/hello/v2/appid -i +HTTP/1.1 200 OK +``` + +```shell +curl http://127.0.0.1:0080/hello/v2/appid -i +HTTP/1.1 429 Too Many Requests +``` + +示例 3: 如果请求不能被任何 `case` 匹配，则 `workflow` 不会执行任何操作 + +```shell +curl http://127.0.0.1:0080/hello/fake -i +HTTP/1.1 200 OK +``` + +## Disable Plugin + +当你需要禁用 `workflow` 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务： + +```shell +curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d ' +{ + "uri":"/hello/*", + "upstream": { + "type": "roundrobin", + "nodes": { + "127.0.0.1:1980": 1 + } + } +}' +``` From 4dda24b4eb9a227eb9e310667b46aaa020e1090c Mon Sep 17 00:00:00 2001 From: tzssangglass Date: Mon, 29 Aug 2022 17:56:28 +0800 Subject: [PATCH 2/5] fix code lint --- docs/en/latest/config.json | 3 ++- docs/zh/latest/config.json | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json index 2e406005d09d..92ac0df8eb54 100644 --- a/docs/en/latest/config.json +++ b/docs/en/latest/config.json @@ -106,7 +106,8 @@ "plugins/traffic-split", "plugins/request-id", "plugins/proxy-control", - "plugins/client-control" + "plugins/client-control", + "plugins/workflow" ] }, { diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json index 6d70ff30e197..31e61bb1df26 100644 --- a/docs/zh/latest/config.json +++ b/docs/zh/latest/config.json @@ -110,7 +110,8 @@ "plugins/traffic-split", "plugins/request-id", "plugins/proxy-control", - "plugins/client-control" + "plugins/client-control", + "plugins/workflow" ] }, { From babfd013e69e010114343af91e8e744144e6a102 Mon Sep 17 00:00:00 2001 From: tzssangglass Date: Tue, 30 Aug 2022 10:28:03 +0800 Subject: [PATCH 3/5] resolve code review --- docs/en/latest/plugins/workflow.md | 17 ++++++++++------- docs/zh/latest/plugins/workflow.md | 17 ++++++++++------- 2 files changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/en/latest/plugins/workflow.md b/docs/en/latest/plugins/workflow.md index db48e9b54400..c918ad50506e 100644 --- a/docs/en/latest/plugins/workflow.md +++ b/docs/en/latest/plugins/workflow.md @@ -4,7 +4,8 @@ keywords: - APISIX - Plugin - workflow -description: This document contains information about the Apache APISIX workflow Plugin. + - traffic control +description: This document describes the Apache APISIX workflow Plugin, you can use it to control traffic. ---