Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(plugin): refactor limit-conn.md #7857

Merged
merged 4 commits into from
Sep 7, 2022
Merged

docs(plugin): refactor limit-conn.md #7857

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a6541ae
docs: update limit-conn.md
lunarwhite Sep 4, 2022
3e28ab1
update ref reviews
lunarwhite Sep 5, 2022
e7d9fbf
update ref reviews
lunarwhite Sep 6, 2022
33eb70f
update ref reviews
lunarwhite Sep 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 44 additions & 53 deletions docs/en/latest/plugins/limit-conn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,9 @@
title: limit-conn
keywords:
- APISIX
- Plugin
- API Gateway
- Limit Connection
- limit-con
description: This document contains information about the Apache APISIX limit-con Plugin.
description: This document contains information about the Apache APISIX limit-con Plugin, you can use it to limits the number of concurrent requests to your services.
---

<!--
Expand Down Expand Up @@ -40,7 +39,7 @@ The `limit-con` Plugin limits the number of concurrent requests to your services
| default_conn_delay | number | True | | default_conn_delay > 0 | Delay in seconds to process the concurrent requests exceeding `conn` (and `conn` + `burst`). |
| only_use_default_delay | boolean | False | false | [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_type | string | False | "var" | ["var", "var_combination"] | Type of user specified key to use. |
| key | string | True | | | User 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. |
| key | string | True | | | User 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_code | string | False | 503 | [200,...,599] | HTTP status code returned when the requests exceeding the threshold are rejected. |
| rejected_msg | string | False | | non-empty | Body of the response returned when the requests exceeding the threshold are rejected. |
| allow_degradation | boolean | False | false | | When set to `true` enables Plugin degradation when the Plugin is temporarily unavailable and allows requests to continue. |
Expand All @@ -49,8 +48,9 @@ The `limit-con` Plugin limits the number of concurrent requests to your services

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

```bash
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
Expand All @@ -75,8 +75,9 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13

You can also configure the `key_type` to `var_combination` as shown:

```bash
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/index.html",
Expand All @@ -99,19 +100,17 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```

<!-- ![enable limit-conn plugin](https://raw.githubusercontent.com/apache/apisix/master/docs/assets/images/plugin/limit-conn-1.png) -->

## Example usage

The example above configures the Plugin to only allow one concurrent request. When more than one request is received, the Plugin will respond with a 503 status code:
lunarwhite marked this conversation as resolved.
Show resolved Hide resolved

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

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

```bash
```shell
<html>
<head><title>503 Service Temporarily Unavailable</title></head>
<body>
Expand All @@ -121,35 +120,15 @@ curl -i http://127.0.0.1:9080/index.html?sleep=20
</html>
```

## Disable Plugin

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

```bash
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
}
}
}'
```

## 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.

````shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/ws",
"enable_websocket": true,
Expand All @@ -170,13 +149,13 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}
}
}'
````
```

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
2. Initiate a WebSocket request, and the connection is established successfully.

````shell
```shell
curl --include \
--no-buffer \
--header "Connection: Upgrade" \
Expand All @@ -189,28 +168,40 @@ curl --include \

```shell
HTTP/1.1 101 Switching Protocols
Connection: upgrade
Upgrade: websocket
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Server: APISIX/2.15.0
...
````
```

3. Initiate the WebSocket request again in another terminal, the request will be rejected
3. Initiate the WebSocket request again in another terminal, the request will be rejected.

````shell
```shell
HTTP/1.1 503 Service Temporarily Unavailable
Date: Mon, 01 Aug 2022 03:49:17 GMT
Content-Type: text/html; charset=utf-8
Content-Length: 194
Connection: keep-alive
Server: APISIX/2.15.0

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

## Disable Plugin

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

```shell
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
}
}
}'
```
Loading