Skip to main content
Version: 3.10

workflow

Description#

The workflow plugin is used to introduce lua-resty-expr to provide complex traffic control features.

Attributes#

NameTypeRequiredDefaultValid valuesDescription
rules.casearray[array]TrueList 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.
rules.actionsarray[object]TrueThe 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#

NameTypeRequiredDefaultValid valuesDescription
actions[1].returnstringFalseReturn directly to the client.
actions[1].[2].codeintegerFalseHTTP status code returned to the client.

limit-count#

NameTypeRequiredDefaultValid valuesDescription
actions[1].limit-countstringFalseExecute the functions of the limit-count plugin.
actions[1].[2]objectFalseConfiguration 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.

Enable Plugin#

You can configure the workflow plugin on a Route as shown below:

note

You can fetch the admin_key from config.yaml and save to an environment variable with the following command:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -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

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

curl http://127.0.0.1:9080/hello/v2/appid -i
HTTP/1.1 200 OK
curl http://127.0.0.1:9080/hello/v2/appid -i
HTTP/1.1 200 OK
curl http://127.0.0.1:9080/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

curl http://127.0.0.1:9080/hello/fake -i
HTTP/1.1 200 OK

Delete Plugin#

To remove 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.

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
"uri":"/hello/*",
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'