api-breaker

Description

The plugin implements API fuse functionality to help us protect our upstream business services.

About the breaker timeout logic

the code logic automatically triggers the unhealthy state incrementation of the number of operations.

Whenever the upstream service returns a status code from the unhealthy.http_statuses configuration (e.g., 500), up to unhealthy.failures (e.g., three times) and considers the upstream service to be in an unhealthy state.

The first time unhealthy status is triggered, broken for 2 seconds.

Then, the request is forwarded to the upstream service again after 2 seconds, and if the unhealthy.http_statuses status code is returned, and the count reaches unhealthy.failures again, broken for 4 seconds.

and so on, 2, 4, 8, 16, 32, 64, ..., 256, 300. 300 is the maximum value of max_breaker_sec, allow users to specify.

In an unhealthy state, when a request is forwarded to an upstream service and the status code in the healthy.http_statuses configuration is returned (e.g., 200) that healthy.successes is reached (e.g., three times), and the upstream service is considered healthy again.

Attributes

Name	Type	Requirement	Default	Valid	Description
break_response_code	integer	required		[200, ..., 599]	Return error code when unhealthy
max_breaker_sec	integer	optional	300	>=3	Maximum breaker time(seconds)
unhealthy.http_statuses	array[integer]	optional	{500}	[500, ..., 599]	Status codes when unhealthy
unhealthy.failures	integer	optional	3	>=1	Number of consecutive error requests that triggered an unhealthy state
healthy.http_statuses	array[integer]	optional	{200}	[200, ..., 499]	Status codes when healthy
healthy.successes	integer	optional	3	>=1	Number of consecutive normal requests that trigger health status

How To Enable

Here's an example, enable the api-breaker plugin on the specified route.

Response 500 or 503 three times in a row to trigger a unhealthy. Response 200 once in a row to restore healthy.

curl "http://127.0.0.1:9080/apisix/admin/routes/1" -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "plugins": {
        "api-breaker": {
            "break_response_code": 502,
            "unhealthy": {
                "http_statuses": [500, 503],
                "failures": 3
            },
            "healthy": {
                "http_statuses": [200],
                "successes": 1
            }
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    },
    "uri": "/hello",
}'

Test Plugin

Then. Like the configuration above, if your upstream service returns 500. 3 times in a row. The client will receive a 502 (break_response_code) response.

$ curl -i -X POST "http://127.0.0.1:9080/hello"
HTTP/1.1 502 Bad Gateway
Content-Type: application/octet-stream
Connection: keep-alive
Server: APISIX/1.5

... ...

Disable Plugin

When you want to disable the api-breaker plugin, it is very simple, you can delete the corresponding json configuration in the plugin configuration, no need to restart the service, it will take effect immediately:

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

The api-breaker plugin has been disabled now. It works for other plugins.