This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 8f763c789 docs: add docs of workflow plugin (#7813)
8f763c789 is described below
commit 8f763c789d778d67a80c59aa6a3c3dfed6fe62aa
Author: tzssangglass <[email protected]>
AuthorDate: Wed Aug 31 15:34:13 2022 +0800
docs: add docs of workflow plugin (#7813)
---
docs/en/latest/config.json | 3 +-
docs/en/latest/plugins/workflow.md | 165 +++++++++++++++++++++++++++++++++++++
docs/zh/latest/config.json | 3 +-
docs/zh/latest/plugins/workflow.md | 165 +++++++++++++++++++++++++++++++++++++
4 files changed, 334 insertions(+), 2 deletions(-)
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index edb489ce4..05ee49c9e 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -162,7 +162,8 @@
"plugins/serverless",
"plugins/azure-functions",
"plugins/openwhisk",
- "plugins/aws-lambda"
+ "plugins/aws-lambda",
+ "plugins/workflow"
]
},
{
diff --git a/docs/en/latest/plugins/workflow.md
b/docs/en/latest/plugins/workflow.md
new file mode 100644
index 000000000..9fe784596
--- /dev/null
+++ b/docs/en/latest/plugins/workflow.md
@@ -0,0 +1,165 @@
+---
+title: workflow
+keywords:
+ - APISIX
+ - Plugin
+ - workflow
+ - traffic control
+description: This document describes the Apache APISIX workflow Plugin, you
can use it to control traffic.
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+## 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, you can refer to
[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`. |
+
+### `actions` Attributes
+
+#### return
+
+| Name | Type | Required | Default | Valid values |
Description |
+| ---------------------- | ------------- | -------- | ------- | ------------ |
---------------------------------------------------------- |
+| actions[1].return | string | False | | |
Return directly to the client. |
+| actions[1].[2].code | integer | False | | |
HTTP status code returned to the client. |
+
+#### limit-count
+
+| Name | Type | Required | Default | Valid values |
Description |
+| ---------------------- | ------------- | -------- | ------- | ------------ |
---------------------------------------------------------------- |
+| actions[1].limit-count | string | False | | |
Execute the functions of the `limit-count` plugin. |
+| 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 requested uri is `/hello/rejected`, the status code `403`
is returned 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/config.json b/docs/zh/latest/config.json
index 686e68a00..252788b40 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -166,7 +166,8 @@
"plugins/serverless",
"plugins/azure-functions",
"plugins/openwhisk",
- "plugins/aws-lambda"
+ "plugins/aws-lambda",
+ "plugins/workflow"
]
},
{
diff --git a/docs/zh/latest/plugins/workflow.md
b/docs/zh/latest/plugins/workflow.md
new file mode 100644
index 000000000..5eba62d7f
--- /dev/null
+++ b/docs/zh/latest/plugins/workflow.md
@@ -0,0 +1,165 @@
+---
+title: workflow
+keywords:
+ - APISIX
+ - Plugin
+ - workflow
+ - 流量控制
+description: 本文介绍了关于 Apache APISIX `workflow` 插件的基本信息及使用方法，你可以基于此插件进行复杂的流量操作。
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+## 描述
+
+`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-lis [...]
+| rules.actions | array[object] | 是 | |
| 当 `case` 成功匹配时要执行的 `actions`。目前，`actions` 中只支持一个元素。`actions`
的唯一元素的第一个子元素可以是 `return` 或 `limit-count`。 |
+
+### `actions` 属性
+
+#### return
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+| ------------- | ------ | ------ | ------------------------ | ----|
------------- |
+| actions[1].return | string | 否 | | | 直接返回到客户端。 |
+| actions[1].[2].code | integer | 否 | | | 返回给客户端的 HTTP 状态码。 |
+
+#### limit-count
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+| ------------- | ------ | ------ | ------------------------ | ----|
------------- |
+| actions[1].limit-count | string | 否 | | | 执行 `limit-count` 插件的功能。 |
+| 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
+ }
+ }
+}'
+```
