Skip to main content
Version: 3.6

limit-conn

Description#

The limit-conn Plugin limits the number of concurrent requests to your services.

Attributes#

NameTypeRequiredDefaultValid valuesDescription
connintegerTrueconn > 0Maximum number of concurrent requests allowed. Requests exceeding this ratio (and below conn + burst) will be delayed (configured by default_conn_delay).
burstintegerTrueburst >= 0Number of additional concurrent requests allowed to be delayed per second. If the number exceeds this hard limit, they will get rejected immediately.
default_conn_delaynumberTruedefault_conn_delay > 0Delay in seconds to process the concurrent requests exceeding conn (and conn + burst).
only_use_default_delaybooleanFalsefalse[true,false]When set to true, the Plugin will always set a delay of default_conn_delay and would not use any other calculations.
key_typestringFalse"var"["var", "var_combination"]Type of user specified key to use.
keystringTrueUser specified key to base the request limiting on. If the key_type attribute is set to "var", the key will be treated as a name of variable, like remote_addr or consumer_name. If the key_type is set to "var_combination", the key will be a combination of variables, like $remote_addr $consumer_name. If the value of the key is empty, remote_addr will be set as the default key.
rejected_codestringFalse503[200,...,599]HTTP status code returned when the requests exceeding the threshold are rejected.
rejected_msgstringFalsenon-emptyBody of the response returned when the requests exceeding the threshold are rejected.
allow_degradationbooleanFalsefalseWhen set to true enables Plugin degradation when the Plugin is temporarily unavailable and allows requests to continue.

Enable Plugin#

You can enable the Plugin on a Route as shown below:

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
"plugins": {
"limit-conn": {
"conn": 1,
"burst": 0,
"default_conn_delay": 0.1,
"rejected_code": 503,
"key_type": "var",
"key": "http_a"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'

You can also configure the key_type to var_combination as shown:

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
"plugins": {
"limit-conn": {
"conn": 1,
"burst": 0,
"default_conn_delay": 0.1,
"rejected_code": 503,
"key_type": "var_combination",
"key": "$consumer_name $remote_addr"
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'

Example usage#

The example above configures the Plugin to only allow one connection on this route. When more than one request is received, the Plugin will respond with a 503 HTTP status code and reject the connection:

curl -i http://127.0.0.1:9080/index.html?sleep=20 &

curl -i http://127.0.0.1:9080/index.html?sleep=20
<html>
<head><title>503 Service Temporarily Unavailable</title></head>
<body>
<center><h1>503 Service Temporarily Unavailable</h1></center>
<hr><center>openresty</center>
</body>
</html>

Delete Plugin#

To remove the limit-conn 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: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
"id": 1,
"plugins": {
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:1980": 1
}
}
}'

Example of application scenarios#

Limit the number of concurrent WebSocket connections#

Apache APISIX supports WebSocket proxy, we can use limit-conn plugin to limit the number of concurrent WebSocket connections.

  1. Create a Route, enable the WebSocket proxy and the limit-conn plugin.

    curl http://127.0.0.1:9180/apisix/admin/routes/1 \
    -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
    {
    "uri": "/ws",
    "enable_websocket": true,
    "plugins": {
    "limit-conn": {
    "conn": 1,
    "burst": 0,
    "default_conn_delay": 0.1,
    "rejected_code": 503,
    "key_type": "var",
    "key": "remote_addr"
    }
    },
    "upstream": {
    "type": "roundrobin",
    "nodes": {
    "127.0.0.1:1980": 1
    }
    }
    }'

    The above route enables the WebSocket proxy on /ws, and limits the number of concurrent WebSocket connections to 1. More than 1 concurrent WebSocket connection will return 503 to reject the request.

  2. Initiate a WebSocket request, and the connection is established successfully.

    curl --include \
    --no-buffer \
    --header "Connection: Upgrade" \
    --header "Upgrade: websocket" \
    --header "Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==" \
    --header "Sec-WebSocket-Version: 13" \
    --http1.1 \
    http://127.0.0.1:9080/ws
    HTTP/1.1 101 Switching Protocols
  3. Initiate the WebSocket request again in another terminal, the request will be rejected.

    HTTP/1.1 503 Service Temporarily Unavailable
    ···
    <html>
    <head><title>503 Service Temporarily Unavailable</title></head>
    <body>
    <center><h1>503 Service Temporarily Unavailable</h1></center>
    <hr><center>openresty</center>
    </body>
    </html>