fault-injection

Description

The fault-injection Plugin can be used to test the resiliency of your application. This Plugin will be executed before the other configured Plugins.

The abort attribute will directly return the specified HTTP code to the client and skips executing the subsequent Plugins.

The delay attribute delays a request and executes of the subsequent Plugins.

Attributes

NameTypeRequirementDefaultValidDescription
abort.http_statusintegerrequired[200, …]HTTP status code of the response to return to the client.
abort.bodystringoptionalBody of the response returned to the client. Nginx variables like client addr: $remote_addr\n can be used in the body.
abort.percentageintegeroptional[0, 100]Percentage of requests to be aborted.
abort.varsarray[]optionalRules which are matched before executing fault injection. See lua-resty-expr for a list of available expressions.
delay.durationnumberrequiredDuration of the delay. Can be decimal.
delay.percentageintegeroptional[0, 100]Percentage of requests to be delayed.
delay.varsarray[]optionalRules which are matched before executing fault injection. See lua-resty-expr for a list of available expressions.
fault-injection - 图1IMPORTANT

To use the fault-injection Plugin one of abort or delay must be specified.

fault-injection - 图2tip

vars can have expressions from lua-resty-expr and can flexibly implement AND/OR relationship between rules. For example:

  1. [
  2.     [
  3.         [ "arg_name","==","jack" ],
  4.         [ "arg_age","==",18 ]
  5.     ],
  6.     [
  7.         [ "arg_name2","==","allen" ]
  8.     ]
  9. ]

This means that the relationship between the first two expressions is AND, and the relationship between them and the third expression is OR.

Enabling the Plugin

You can enable the fault-injection Plugin on a specific Route as shown below:

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "plugins": {
  4.        "fault-injection": {
  5.            "abort": {
  6.               "http_status": 200,
  7.               "body": "Fault Injection!"
  8.            }
  9.        }
  10.     },
  11.     "upstream": {
  12.        "nodes": {
  13.            "127.0.0.1:1980": 1
  14.        },
  15.        "type": "roundrobin"
  16.     },
  17.     "uri": "/hello"
  18. }'

Similarly, to enable a delay fault:

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "plugins": {
  4.        "fault-injection": {
  5.            "delay": {
  6.               "duration": 3
  7.            }
  8.        }
  9.     },
  10.     "upstream": {
  11.        "nodes": {
  12.            "127.0.0.1:1980": 1
  13.        },
  14.        "type": "roundrobin"
  15.     },
  16.     "uri": "/hello"
  17. }'

You can also enable the Plugin with both abort and delay which can have vars for matching:

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "plugins": {
  4.         "fault-injection": {
  5.             "abort": {
  6.                 "http_status": 403,
  7.                 "body": "Fault Injection!\n",
  8.                 "vars": [
  9.                     [
  10.                         [ "arg_name","==","jack" ]
  11.                     ]
  12.                 ]
  13.             },
  14.             "delay": {
  15.                 "duration": 2,
  16.                 "vars": [
  17.                     [
  18.                         [ "http_age","==","18" ]
  19.                     ]
  20.                 ]
  21.             }
  22.         }
  23.     },
  24.     "upstream": {
  25.         "nodes": {
  26.             "127.0.0.1:1980": 1
  27.         },
  28.         "type": "roundrobin"
  29.     },
  30.     "uri": "/hello"
  31. }'

Example usage

Once you have enabled the Plugin as shown above, you can make a request to the configured Route:

  1. curl http://127.0.0.1:9080/hello -i
  1. HTTP/1.1 200 OK
  2. Date: Mon, 13 Jan 2020 13:50:04 GMT
  3. Content-Type: text/plain
  4. Transfer-Encoding: chunked
  5. Connection: keep-alive
  6. Server: APISIX web server
  8. Fault Injection!

And if we configure the delay fault:

  1. time curl http://127.0.0.1:9080/hello -i
  1. HTTP/1.1 200 OK
  2. Content-Type: application/octet-stream
  3. Content-Length: 6
  4. Connection: keep-alive
  5. Server: APISIX web server
  6. Date: Tue, 14 Jan 2020 14:30:54 GMT
  7. Last-Modified: Sat, 11 Jan 2020 12:46:21 GMT
  9. hello
  11. real    0m3.034s
  12. user    0m0.007s
  13. sys     0m0.010s

Fault injection with criteria matching

You can enable the fault-injection Plugin with the vars attribute to set specific rules:

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "plugins": {
  4.         "fault-injection": {
  5.             "abort": {
  6.                     "http_status": 403,
  7.                     "body": "Fault Injection!\n",
  8.                     "vars": [
  9.                         [
  10.                             [ "arg_name","==","jack" ]
  11.                         ]
  12.                     ]
  13.             }
  14.         }
  15.     },
  16.     "upstream": {
  17.         "nodes": {
  18.             "127.0.0.1:1980": 1
  19.         },
  20.         "type": "roundrobin"
  21.     },
  22.     "uri": "/hello"
  23. }'

Now, we can test the Route. First, we test with a different name argument:

  1. curl "http://127.0.0.1:9080/hello?name=allen" -i

You will get the expected response without the fault injected:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/octet-stream
  3. Transfer-Encoding: chunked
  4. Connection: keep-alive
  5. Date: Wed, 20 Jan 2021 07:21:57 GMT
  6. Server: APISIX/2.2
  8. hello

Now if we set the name to match our configuration, the fault-injection Plugin is executed:

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

Disable Plugin

To disable the fault-injection 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.

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "uri": "/hello",
  4.     "plugins": {},
  5.     "upstream": {
  6.         "type": "roundrobin",
  7.         "nodes": {
  8.             "127.0.0.1:1980": 1
  9.         }
  10.     }
  11. }'