Skip to content

Commit

Permalink
docs: update "Traffic" Plugin docs 1 (#7030)
Browse files Browse the repository at this point in the history 
Signed-off-by: Navendu Pottekkat <navendupottekkat@gmail.com>
  • Loading branch information
@pottekkat
pottekkat committed May 15, 2022
1 parent d8e4756 commit 1cdcc5c
Show file tree
Hide file tree
Showing 3 changed files with 166 additions and 196 deletions.
62 changes: 32 additions & 30 deletions docs/en/latest/plugins/limit-conn.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
---
title: limit-conn
keywords:
- APISIX
- Plugin
- Limit Connection
- limit-con
description: This document contains information about the Apache APISIX limit-con Plugin.
---

<!--
Expand All @@ -23,27 +29,27 @@ title: limit-conn

## Description

Limiting request concurrency plugin.
The `limit-con` Plugin limits the number of concurrent requests to your services.

## Attributes

| Name | Type | Requirement | Default | Valid | Description |
| ------------------ | ------- | ----------- | ------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conn | integer | required | | conn > 0 | the maximum number of concurrent requests allowed. Requests exceeding this ratio (and below `conn` + `burst`) will get delayed(the latency seconds is configured by `default_conn_delay`) to conform to this threshold. |
| burst | integer | required | | burst >= 0 | the number of excessive concurrent requests (or connections) allowed to be delayed. |
| default_conn_delay | number | required | | default_conn_delay > 0 | the latency seconds of request when concurrent requests exceeding `conn` but below (`conn` + `burst`). |
| only_use_default_delay | boolean | optional | false | [true,false] | enable the strict mode of the latency seconds. If you set this option to `true`, it will run strictly according to the latency seconds you set without additional calculation logic. |
| key_type | string | optional | "var" | ["var", "var_combination"] | the type of key. |
| key | string | required | | | the user specified key to limit the rate. If the `key_type` is "var", the key will be treated as a name of variable, like "remote_addr" or "consumer_name". If the `key_type` is "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 | optional | 503 | [200,...,599] | the HTTP status code returned when the request exceeds `conn` + `burst` will be rejected. |
| rejected_msg | string | optional | | non-empty | the response body returned when the request exceeds `conn` + `burst` will be rejected. |
| allow_degradation | boolean | optional | false | | Whether to enable plugin degradation when the limit-conn function is temporarily unavailable. Allow requests to continue when the value is set to true, default false. |
| Name | Type | Required | Default | Valid values | Description |
| ---------------------- | ------- | -------- | ------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| conn | integer | True | | conn > 0 | Maximum number of concurrent requests allowed. Requests exceeding this ratio (and below `conn` + `burst`) will be delayed (configured by `default_conn_delay`). |
| burst | integer | True | | burst >= 0 | Number of additional concurrent requests allowed to be delayed per second. If the number exceeds this hard limit, they will get rejected immediately. |
| 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. |
| 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. |

## How To Enable
## Enabling the Plugin

Here's an example, enable the limit-conn plugin on the specified route when setting `key_type` to `var` :
You can enable the Plugin on a Route as shown below:

```shell
```bash
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
Expand All @@ -67,9 +73,9 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```

Here's an example, enable the limit-conn plugin on the specified route when setting `key_type` to `var_combination` :
You can also configure the `key_type` to `var_combination` as shown:

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

You also can complete the above operation through the web interface, first add a route, then add limit-conn plugin:
![enable limit-conn plugin](../../../assets/images/plugin/limit-conn-1.png)
<!-- ![enable limit-conn plugin](https://raw.githubusercontent.com/apache/apisix/master/docs/assets/images/plugin/limit-conn-1.png) -->

## Test Plugin
## Example usage

The parameters of the plugin enabled above indicate that only one concurrent request is allowed. When more than one concurrent request is received, will return `503` directly.
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:

```shell
```bash
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
<html>
<head><title>503 Service Temporarily Unavailable</title></head>
<body>
Expand All @@ -113,15 +121,11 @@ curl -i http://127.0.0.1:9080/index.html?sleep=20
</html>
```

This means that the limit request concurrency plugin is in effect.

## Disable Plugin

When you want to disable the limit-conn 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:
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
```bash
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
Expand All @@ -137,5 +141,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}
}'
```

The limit-conn plugin has been disabled now. It works for other plugins.
Loading

0 comments on commit 1cdcc5c

Please sign in to comment.