Version: 2.13

fault-injection

描述#

故障注入插件，该插件可以和其他插件一起使用，并且会在其他插件前被执行，配置 abort 参数将直接返回给客户端指定的响应码并且终止其他插件的执行，配置 delay 参数将延迟某个请求，并且还会执行配置的其他插件。

参数#

名称	类型	必选项	有效值	描述
abort.http_status	integer	必需	[200, ...]	返回给客户端的 http 状态码
abort.body	string	可选		返回给客户端的响应数据。支持使用 Nginx 变量，如 `client addr: $remote_addr\n`
abort.percentage	integer	可选	[0, 100]	将被中断的请求占比
abort.vars	array[]	可选		执行故障注入的规则，当规则匹配通过后才会执行故障注。`vars` 是一个表达式的列表，来自 lua-resty-expr。
delay.duration	number	必需		延迟时间，可以指定小数
delay.percentage	integer	可选	[0, 100]	将被延迟的请求占比
delay.vars	array[]	可选		执行请求延迟的规则，当规则匹配通过后才会延迟请求。`vars` 是一个表达式列表，来自 lua-resty-expr。

注：参数 abort 和 delay 至少要存在一个。

vars 是由 lua-resty-expr 的表达式组成的列表，它可以灵活的实现规则之间的 and/or 关系，示例：

[
    [
        [ "arg_name","==","jack" ],
        [ "arg_age","==",18 ]
    ],
    [
        [ "arg_name2","==","allen" ]
    ]
]

这表示前两个表达式之间的关系是 and ，而前两个和第三个表达式之间的关系是 or。

示例#

启用插件#

示例1：为特定路由启用 fault-injection 插件，并指定 abort 参数：

curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "plugins": {
       "fault-injection": {
           "abort": {
              "http_status": 200,
              "body": "Fault Injection!"
           }
       }
    },
    "upstream": {
       "nodes": {
           "127.0.0.1:1980": 1
       },
       "type": "roundrobin"
    },
    "uri": "/hello"
}'

测试：

$ curl http://127.0.0.1:9080/hello -i
HTTP/1.1 200 OK
Date: Mon, 13 Jan 2020 13:50:04 GMT
Content-Type: text/plain
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX web server

Fault Injection!

http status 返回 200 并且响应 body 为 Fault Injection!，表示该插件已启用。

示例2：为特定路由启用 fault-injection 插件，并指定 delay 参数：

curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "plugins": {
       "fault-injection": {
           "delay": {
              "duration": 3
           }
       }
    },
    "upstream": {
       "nodes": {
           "127.0.0.1:1980": 1
       },
       "type": "roundrobin"
    },
    "uri": "/hello"
}'

测试：

$ time curl http://127.0.0.1:9080/hello -i
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Content-Length: 6
Connection: keep-alive
Server: APISIX web server
Date: Tue, 14 Jan 2020 14:30:54 GMT
Last-Modified: Sat, 11 Jan 2020 12:46:21 GMT

hello

real    0m3.034s
user    0m0.007s
sys     0m0.010s

示例3：为特定路由启用 fault-injection 插件，并指定 abort 参数的 vars 规则。

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "plugins": {
        "fault-injection": {
            "abort": {
                    "http_status": 403,
                    "body": "Fault Injection!\n",
                    "vars": [
                        [
                            [ "arg_name","==","jack" ]
                        ]
                    ]
            }
        }
    },
    "upstream": {
        "nodes": {
            "127.0.0.1:1980": 1
        },
        "type": "roundrobin"
    },
    "uri": "/hello"
}'

测试：

1、vars 规则匹配失败，请求返回上游响应数据：

$ curl "http://127.0.0.1:9080/hello?name=allen" -i
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Transfer-Encoding: chunked
Connection: keep-alive
Date: Wed, 20 Jan 2021 07:21:57 GMT
Server: APISIX/2.2

hello

2、vars 规则匹配成功，执行故障注入：

$ curl "http://127.0.0.1:9080/hello?name=jack" -i
HTTP/1.1 403 Forbidden
Date: Wed, 20 Jan 2021 07:23:37 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.2

Fault Injection!

示例4：为特定路由启用 fault-injection 插件，并指定 delay 参数的 vars 规则。

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "plugins": {
        "fault-injection": {
            "delay": {
                "duration": 2,
                "vars": [
                    [
                        [ "arg_name","==","jack" ]
                    ]
                ]
            }
        }
    },
    "upstream": {
        "nodes": {
            "127.0.0.1:1980": 1
        },
        "type": "roundrobin"
    },
    "uri": "/hello"
}'

测试：

1、vars 规则匹配失败，不延迟请求：

$ time "curl http://127.0.0.1:9080/hello?name=allen" -i
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Transfer-Encoding: chunked
Connection: keep-alive
Date: Wed, 20 Jan 2021 07:26:17 GMT
Server: APISIX/2.2

hello

real    0m0.007s
user    0m0.003s
sys     0m0.003s

2、vars 规则匹配成功，延迟请求两秒：

$ time curl "http://127.0.0.1:9080/hello?name=jack" -i
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Transfer-Encoding: chunked
Connection: keep-alive
Date: Wed, 20 Jan 2021 07:57:50 GMT
Server: APISIX/2.2

hello

real    0m2.009s
user    0m0.004s
sys     0m0.004s

示例5：为特定路由启用 fault-injection 插件，并指定 abort 和 delay 参数的 vars 规则。

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "plugins": {
        "fault-injection": {
            "abort": {
                "http_status": 403,
                "body": "Fault Injection!\n",
                "vars": [
                    [
                        [ "arg_name","==","jack" ]
                    ]
                ]
            },
            "delay": {
                "duration": 2,
                "vars": [
                    [
                        [ "http_age","==","18" ]
                    ]
                ]
            }
        }
    },
    "upstream": {
        "nodes": {
            "127.0.0.1:1980": 1
        },
        "type": "roundrobin"
    },
    "uri": "/hello"
}'

测试：

1、abort 和 delay 的 vars 规则匹配失败：

$ time curl "http://127.0.0.1:9080/hello?name=allen" -H 'age: 20' -i
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Transfer-Encoding: chunked
Connection: keep-alive
Date: Wed, 20 Jan 2021 08:01:43 GMT
Server: APISIX/2.2

hello

real    0m0.007s
user    0m0.003s
sys     0m0.003s

2、abort 的 vars 规则匹配失败，不执行故障注入，但延迟请求：

$ time curl "http://127.0.0.1:9080/hello?name=allen" -H 'age: 18' -i
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Transfer-Encoding: chunked
Connection: keep-alive
Date: Wed, 20 Jan 2021 08:19:03 GMT
Server: APISIX/2.2

hello

real    0m2.009s
user    0m0.001s
sys     0m0.006s

3、delay 的 vars 规则匹配失败，不延迟请求，但执行故障注入：

$ time curl "http://127.0.0.1:9080/hello?name=jack" -H 'age: 20' -i
HTTP/1.1 403 Forbidden
Date: Wed, 20 Jan 2021 08:20:18 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.2

Fault Injection!

real    0m0.007s
user    0m0.002s
sys     0m0.004s

4、abort 和 delay 参数的 vars 规则匹配成功，执行故障注入，并延迟请求：

$ time curl "http://127.0.0.1:9080/hello?name=jack" -H 'age: 18' -i
HTTP/1.1 403 Forbidden
Date: Wed, 20 Jan 2021 08:21:17 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.2

Fault Injection!

real    0m2.006s
user    0m0.001s
sys     0m0.005s

示例6：为特定路由启用 fault-injection 插件，并指定 abort 参数的 vars 规则（or 的关系）。

curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "plugins": {
        "fault-injection": {
            "abort": {
                "http_status": 403,
                "body": "Fault Injection!\n",
                "vars": [
                    [
                        ["arg_name","==","jack"],
                        ["arg_age","!","<",18]
                    ],
                    [
                        ["http_apikey","==","apisix-key"]
                    ]
                ]
            }
        }
    },
    "upstream": {
        "nodes": {
            "127.0.0.1:1980": 1
        },
        "type": "roundrobin"
    },
    "uri": "/hello"
}'

表示当请求参数 name 和 age 同时满足 name == "jack"、age >= 18 时，执行故障注入。或请求头 apikey 满足 apikey == "apisix-key" 时，执行故障注入。

测试：

1、请求参数 name 和 age 匹配成功，缺少请求头 apikey，执行故障注入：

$ curl "http://127.0.0.1:9080/hello?name=jack&age=19" -i
HTTP/1.1 403 Forbidden
Date: Fri, 22 Jan 2021 11:05:46 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.2

Fault Injection!

2、请求头 apikey 匹配成功，缺少请求参数，执行故障注入：

$ curl http://127.0.0.1:9080/hello -H "apikey: apisix-key" -i
HTTP/1.1 403 Forbidden
Date: Fri, 22 Jan 2021 11:08:34 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/2.2

Fault Injection!

3、请求参数与请求头都匹配失败，不执行故障注入：

$ curl http://127.0.0.1:9080/hello -i
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Transfer-Encoding: chunked
Connection: keep-alive
Date: Fri, 22 Jan 2021 11:11:17 GMT
Server: APISIX/2.2

hello

禁用插件#

移除插件配置中相应的 JSON 配置可立即禁用该插件，无需重启服务：

curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/hello",
    "plugins": {},
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'

这时该插件已被禁用。