You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sp...@apache.org on 2022/05/15 11:35:14 UTC
[apisix] branch master updated: docs: update "Traffic" Plugin docs 1 (#7030)
This is an automated email from the ASF dual-hosted git repository.
spacewander pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 1cdcc5caf docs: update "Traffic" Plugin docs 1 (#7030)
1cdcc5caf is described below
commit 1cdcc5caffc7ccf3825e3be43f62af8388b93551
Author: Navendu Pottekkat <na...@gmail.com>
AuthorDate: Sun May 15 17:05:06 2022 +0530
docs: update "Traffic" Plugin docs 1 (#7030)
Signed-off-by: Navendu Pottekkat <na...@gmail.com>
---
docs/en/latest/plugins/limit-conn.md | 62 ++++++-------
docs/en/latest/plugins/limit-count.md | 141 ++++++++++++++----------------
docs/en/latest/plugins/limit-req.md | 159 ++++++++++++++--------------------
3 files changed, 166 insertions(+), 196 deletions(-)
diff --git a/docs/en/latest/plugins/limit-conn.md b/docs/en/latest/plugins/limit-conn.md
index d42316519..508ed1c58 100644
--- a/docs/en/latest/plugins/limit-conn.md
+++ b/docs/en/latest/plugins/limit-conn.md
@@ -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.
---
<!--
@@ -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"],
@@ -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"],
@@ -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:
-
+<!--  -->
-## 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>
@@ -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"],
@@ -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.
diff --git a/docs/en/latest/plugins/limit-count.md b/docs/en/latest/plugins/limit-count.md
index e63f88513..20dbfbc97 100644
--- a/docs/en/latest/plugins/limit-count.md
+++ b/docs/en/latest/plugins/limit-count.md
@@ -1,5 +1,11 @@
---
title: limit-count
+keywords:
+ - APISIX
+ - Plugin
+ - Limit Count
+ - limit-count
+description: This document contains information about the Apache APISIX limit-count Plugin.
---
<!--
@@ -23,35 +29,35 @@ title: limit-count
## Description
-Limit request rate by a fixed number of requests in a given time window.
+The `limit-count` Plugin limits the number of requests to your service by a given count per time.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| ------------------- | ------- | --------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| count | integer | required | | count > 0 | the specified number of requests threshold. |
-| time_window | integer | required | | time_window > 0 | the time window in seconds before the request count is reset. |
-| key_type | string | optional | "var" | ["var", "var_combination", "constant"] | the type of key. |
-| key | string | optional | "remote_addr" | | the user specified key to limit the rate. If the `key_type` is "constant", the key will be treated as a constant. If the `key_type` is "var", the key will be treated as a name of variable. If the `key_type` is "var_combination", the key will be a combination of variables. For example, if we use "$remote_addr $consumer_name" as key, plugin will be restricted by two variables which are "remote_addr" and "consumer_name". If [...]
-| rejected_code | integer | optional | 503 | [200,...,599] | The HTTP status code returned when the request exceeds the threshold is rejected, default 503. |
-| rejected_msg | string | optional | | non-empty | The response body returned when the request exceeds the threshold is rejected. |
-| policy | string | optional | "local" | ["local", "redis", "redis-cluster"] | The rate-limiting policies to use for retrieving and incrementing the limits. Available values are `local`(the counters will be stored locally in-memory on the node), `redis`(counters are stored on a Redis server and will be shared across the nodes, usually use it to do the global speed limit) [...]
-| allow_degradation | boolean | optional | false | | Whether to enable plugin degradation when the limit-count function is temporarily unavailable(e.g. redis timeout). Allow requests to continue when the value is set to true, default false. |
-| show_limit_quota_header | boolean | optional | true | | Whether show `X-RateLimit-Limit` and `X-RateLimit-Remaining` (which mean the total number of requests and the remaining number of requests that can be sent) in the response header, default true. |
-| group | string | optional | | non-empty | Route configured with the same group will share the same counter |
-| redis_host | string | required for `redis` | | | When using the `redis` policy, this property specifies the address of the Redis server. |
-| redis_port | integer | optional | 6379 | [1,...] | When using the `redis` policy, this property specifies the port of the Redis server. |
-| redis_password | string | optional | | | When using the `redis` or `redis-cluster` policy, this property specifies the password of the Redis server. [...]
-| redis_database | integer | optional | 0 | redis_database >= 0 | When using the `redis` policy, this property specifies the database you selected of the Redis server, and only for non Redis cluster mode (single instance mode or Redis public cloud service that provides single entry). |
-| redis_timeout | integer | optional | 1000 | [1,...] | When using the `redis` or `redis-cluster` policy, this property specifies the timeout in milliseconds of any command submitted to the Redis server. [...]
-| redis_cluster_nodes | array | required when policy is `redis-cluster` | | | When using `redis-cluster` policy，This property is a list of addresses of Redis cluster service nodes (at least two). [...]
-| redis_cluster_name | string | required when policy is `redis-cluster` | | | When using `redis-cluster` policy, this property is the name of Redis cluster service nodes. [...]
-
-## How To Enable
-
-Here's an example, enable the `limit count` plugin on the specified route when setting `key_type` to `var` :
-
-```shell
+| Name | Type | Required | Default | Valid values | Description [...]
+| ----------------------- | ------- | ----------------------------------------- | ------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- [...]
+| count | integer | True | | count > 0 | Maximum number of requests to allow. [...]
+| time_window | integer | True | | time_window > 0 | Time in seconds before `count` is reset. [...]
+| key_type | string | False | "var" | ["var", "var_combination", "constant"] | Type of user specified key to use. [...]
+| key | string | False | "remote_addr" | | User specified key to base the request limiting on. If the `key_type` attribute is set to `constant`, the key will be treated as a constant value. 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 combinatio [...]
+| rejected_code | integer | 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. [...]
+| policy | string | False | "local" | ["local", "redis", "redis-cluster"] | Rate-limiting policies to use for retrieving and increment the limit count. When set to `local` the counters will be locally stored in memory on the node. When set to `redis` counters are stored on a Redis server and will be shared across the nodes. It is done usually for global speed limiting, and setting to `redis-cluster` uses a Redis cluster inste [...]
+| allow_degradation | boolean | False | false | | When set to `true` enables Plugin degradation when the Plugin is temporarily unavailable (for example, a Redis timeout) and allows requests to continue. [...]
+| show_limit_quota_header | boolean | False | true | | When set to `true`, adds `X-RateLimit-Limit` (total number of requests) and `X-RateLimit-Remaining` (remaining number of requests) to the response header. [...]
+| group | string | False | | non-empty | Group to share the counter with. Routes configured with the same group will share the counter. [...]
+| redis_host | string | required when `policy` is `redis` | | | Address of the Redis server. Used when the `policy` attribute is set to `redis`. [...]
+| redis_port | integer | False | 6379 | [1,...] | Port of the Redis server. Used when the `policy` attribute is set to `redis`. [...]
+| redis_password | string | False | | | Password of the Redis server. Used when the `policy` is set to `redis` or `redis-cluster`. [...]
+| redis_database | integer | False | 0 | redis_database >= 0 | Selected database of the Redis server (for single instance operation or when using Redis cloud with a single entrypoint). Used when the `policy` attribute is set to `redis`. [...]
+| redis_timeout | integer | False | 1000 | [1,...] | Timeout in milliseconds for any command submitted to the Redis server. Used when the `policy` attribute is set to `redis` or `redis-cluster`. [...]
+| redis_cluster_nodes | array | required when `policy` is `redis-cluster` | | | Addresses of Redis cluster nodes. Used when the `policy` attribute is set to `redis-cluster`. [...]
+| redis_cluster_name | string | required when `policy` is `redis-cluster` | | | Name of the Redis cluster service nodes. Used when the `policy` attribute is set to `redis-cluster`. [...]
+
+## Enabling the Plugin
+
+You can enable the Plugin on a Route as shown below:
+
+```bash
curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
@@ -73,9 +79,9 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335
}'
```
-Here's an example, enable the `limit count` 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 -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
@@ -97,12 +103,11 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335
}'
```
-You also can complete the above operation through the web interface, first add a route, then add limit-count plugin:
-
+<!--  -->
-It is possible to share the same limit counter across different routes. For example,
+You can also create a group to share the same counter across multiple Routes:
-```shell
+```bash
curl -i http://127.0.0.1:9080/apisix/admin/services/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
@@ -123,34 +128,35 @@ curl -i http://127.0.0.1:9080/apisix/admin/services/1 -H 'X-API-KEY: edd1c9f0343
}'
```
-Every route which group name is "services_1#1640140620" will share the same count limitation `1` in one minute per remote_addr.
+Now every Route which belongs to group `services_1#1640140620` (or the service with ID `1`) will share the same counter.
-```shell
-$ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+```bash
+curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"service_id": "1",
"uri": "/hello"
}'
+```
-$ curl -i http://127.0.0.1:9080/apisix/admin/routes/2 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+```bash
+curl -i http://127.0.0.1:9080/apisix/admin/routes/2 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"service_id": "1",
"uri": "/hello2"
}'
+```
-$ curl -i http://127.0.0.1:9080/hello
-HTTP/1.1 200 ...
-
-$ curl -i http://127.0.0.1:9080/hello2
-HTTP/1.1 503 ...
+```bash
+curl -i http://127.0.0.1:9080/hello
```
-Note that every limit-count configuration of the same group must be the same.
-Therefore, once update the configuration, we also need to update the group name.
+```bash
+HTTP/1.1 200 ...
+```
-It is also possible to share the same limit counter in all requests. For example,
+You can also share the same limit counter for all your requests by setting the `key_type` to `constant`:
-```shell
+```bash
curl -i http://127.0.0.1:9080/apisix/admin/services/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
@@ -172,17 +178,13 @@ curl -i http://127.0.0.1:9080/apisix/admin/services/1 -H 'X-API-KEY: edd1c9f0343
}'
```
-Compared with the previous configuration, we set the `key_type` to `constant`.
-By setting `key_type` to `constant`, we don't evaluate the value of `key` but treat it as a constant.
-
-Now every route which group name is "services_1#1640140621" will share the same count limitation `1` in one minute among all the requests,
-even these requests are from different remote_addr.
+Now every request will share the same count limitation regardless of their remote address.
-If you need a cluster-level precision traffic limit, then we can do it with the redis server. The rate limit of the traffic will be shared between different APISIX nodes to limit the rate of cluster traffic.
+For cluster-level traffic limiting, you can use a Redis server. The counter will be shared between different APISIX nodes to achieve traffic limiting.
-Here is the example if we use single `redis` policy:
+The example below shows how you can use the `redis` policy:
-```shell
+```bash
curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
@@ -209,9 +211,9 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335
}'
```
-If using `redis-cluster` policy:
+Similarly you can also configure the `redis-cluster` policy:
-```shell
+```bash
curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/index.html",
@@ -239,18 +241,15 @@ curl -i http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335
}'
```
-## Test Plugin
+## Example usage
-The above configuration limits access to only 2 times in 60 seconds. The first two visits will be normally:
+The above configuration limits to 2 requests in 60 seconds. The first two requests will work and the response headers will contain the headers `X-RateLimit-Limit` and `X-RateLimit-Remaining`:
-```shell
+```bash
curl -i http://127.0.0.1:9080/index.html
```
-The response header contains `X-RateLimit-Limit` and `X-RateLimit-Remaining`,
-which mean the total number of requests and the remaining number of requests that can be sent:
-
-```shell
+```bash
HTTP/1.1 200 OK
Content-Type: text/html
Content-Length: 13175
@@ -260,9 +259,9 @@ X-RateLimit-Remaining: 0
Server: APISIX web server
```
-When you visit for the third time, you will receive a response with the 503 HTTP code:
+When you visit for a third time in the 60 seconds, you will receive a response with 503 code:
-```shell
+```bash
HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: text/html
Content-Length: 194
@@ -278,9 +277,9 @@ Server: APISIX web server
</html>
```
-At the same time, if you set the property `rejected_msg` to `"Requests are too frequent, please try again later."` , when you visit for the third time, you will receive a response body like below:
+You can also set a custom response by configuring the `rejected_msg` attribute:
-```shell
+```bash
HTTP/1.1 503 Service Temporarily Unavailable
Content-Type: text/html
Content-Length: 194
@@ -290,15 +289,11 @@ Server: APISIX web server
{"error_msg":"Requests are too frequent, please try again later."}
```
-This means that the `limit count` plugin is in effect.
-
## Disable Plugin
-When you want to disable the `limit count` 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-count` 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"],
@@ -311,5 +306,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}
}'
```
-
-The `limit count` plugin has been disabled now. It works for other plugins.
diff --git a/docs/en/latest/plugins/limit-req.md b/docs/en/latest/plugins/limit-req.md
index 883cc145b..5760aa557 100644
--- a/docs/en/latest/plugins/limit-req.md
+++ b/docs/en/latest/plugins/limit-req.md
@@ -1,5 +1,11 @@
---
title: limit-req
+keywords:
+ - APISIX
+ - Plugin
+ - Limit Request
+ - limit-req
+description: This document contains information about the Apache APISIX limit-req Plugin.
---
<!--
@@ -23,28 +29,26 @@ title: limit-req
## Description
-limit request rate using the "leaky bucket" method.
+The `limit-req` Plugin limits the number of requests to your service using the [leaky bucket](https://en.wikipedia.org/wiki/Leaky_bucket) algorithm.
## Attributes
-| Name | Type | Requirement | Default | Valid | Description |
-| ------------- | ------- | ----------- | ------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| rate | integer | required | | rate > 0 | the specified request rate (number per second) threshold. Requests exceeding this rate (and below `burst`) will get delayed to conform to the rate. |
-| burst | integer | required | | burst >= 0 | the number of excessive requests per second allowed to be delayed. Requests exceeding this hard limit will get rejected immediately. |
-| 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 | integer | optional | 503 | [200,...,599] | The HTTP status code returned when the request exceeds the threshold is rejected. |
-| rejected_msg | string | optional | | non-empty | The response body returned when the request exceeds the threshold is rejected. |
-| nodelay | boolean | optional | false | | If nodelay flag is true, bursted requests will not get delayed |
-| allow_degradation | boolean | optional | false | | Whether to enable plugin degradation when the limit-req function is temporarily unavailable. Allow requests to continue when the value is set to true, default false. |
+| Name | Type | Required | Default | Valid values | Description |
+|-------------------|---------|----------|---------|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| rate | integer | True | | rate > 0 | Threshold for number of requests per second. Requests exceeding this rate (and below `burst`) will be delayed to match this rate. |
+| burst | integer | True | | burst >= 0 | Number of additional requests allowed to be delayed per second. If the number of requests exceeds this hard limit, they will get rejected immediately. |
+| 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 | integer | 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. |
+| nodelay | boolean | False | false | | If set to `true`, requests within the burst threshold would not be delayed. |
+| allow_degradation | boolean | False | false | | When set to `true` enables Plugin degradation when the Plugin is temporarily unavailable and allows requests to continue. |
-## Example
+## Enabling the Plugin
-### How to enable on the `route` or `service`
+You can enable the Plugin on a Route as shown below:
-Take `route` as an example (the use of `service` is the same method), enable the `limit-req` plugin on the specified route when setting `key_type` to `var` .
-
-```shell
+```bash
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
@@ -67,10 +71,9 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-Take `route` as an example (the use of `service` is the same method), enable the `limit-req` 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
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+```json
{
"methods": ["GET"],
"uri": "/index.html",
@@ -89,59 +92,14 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
"127.0.0.1:9001": 1
}
}
-}'
-```
-
-You also can complete the above operation through the web interface, first add a route, then add limit-req plugin:
-
-
-**Test Plugin**
-
-The above configuration limits the request rate to 1 per second. If it is greater than 1 and less than 3, the delay will be added. If the rate exceeds 3, it will be rejected:
-
-```shell
-curl -i http://127.0.0.1:9080/index.html
-```
-
-When you exceed, you will receive a response header with a 503 return code:
-
-```html
-HTTP/1.1 503 Service Temporarily Unavailable
-Content-Type: text/html
-Content-Length: 194
-Connection: keep-alive
-Server: APISIX web server
-
-<html>
-<head><title>503 Service Temporarily Unavailable</title></head>
-<body>
-<center><h1>503 Service Temporarily Unavailable</h1></center>
-<hr><center>openresty</center>
-</body>
-</html>
-```
-
-At the same time, you set the property `rejected_msg` to `"Requests are too frequent, please try again later."` , when you exceed, you will receive a response body like below:
-
-```shell
-HTTP/1.1 503 Service Temporarily Unavailable
-Content-Type: text/html
-Content-Length: 194
-Connection: keep-alive
-Server: APISIX web server
-
-{"error_msg":"Requests are too frequent, please try again later."}
+}
```
-This means that the limit req plugin is in effect.
+You can also configure the Plugin on specific consumers to limit their requests.
-### How to enable on the `consumer`
+First, you can create a Consumer and enable the `limit-req` Plugin on it:
-To enable the `limit-req` plugin on the consumer, it needs to be used together with the authorization plugin. Here, the key-auth authorization plugin is taken as an example.
-
-1. Bind the `limit-req` plugin to the consumer
-
-```shell
+```bash
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "consumer_jack",
@@ -151,7 +109,7 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
},
"limit-req": {
"rate": 1,
- "burst": 1,
+ "burst": 3,
"rejected_code": 403,
"key": "consumer_name"
}
@@ -159,9 +117,11 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
}'
```
-2. Create a `route` and enable the `key-auth` plugin
+In this example, the [key-auth](./key-auth.md) Plugin is used to authenticate the Consumer.
-```shell
+Next, create a Route and enable the `key-auth` Plugin:
+
+```bash
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
@@ -180,40 +140,57 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-**Test Plugin**
+## Example usage
-The value of `rate + burst` is not exceeded.
+Once you have configured the Plugin as shown above, you can test it out. The above configuration limits to 1 request per second. If the number of requests is greater than 1 but less than 3, a delay will be added. And if the number of requests per second exceeds 3, it will be rejected.
-```shell
-curl -i http://127.0.0.1:9080/index.html -H 'apikey: auth-jack'
-HTTP/1.1 200 OK
-......
+Now if you send a request:
+
+```bash
+curl -i http://127.0.0.1:9080/index.html
```
-When the value of `rate + burst` is exceeded.
+For authenticated requests:
-```shell
+```bash
curl -i http://127.0.0.1:9080/index.html -H 'apikey: auth-jack'
-HTTP/1.1 403 Forbidden
-.....
+```
+
+If you exceed the limit, you will receive a response with a 503 code:
+
+```html
+HTTP/1.1 503 Service Temporarily Unavailable
+Content-Type: text/html
+Content-Length: 194
+Connection: keep-alive
+Server: APISIX web server
+
<html>
-<head><title>403 Forbidden</title></head>
+<head><title>503 Service Temporarily Unavailable</title></head>
<body>
-<center><h1>403 Forbidden</h1></center>
+<center><h1>503 Service Temporarily Unavailable</h1></center>
<hr><center>openresty</center>
</body>
</html>
```
-Explains that the `limit-req` plugin tied to `consumer` has taken effect.
+You can set a custom rejected message by configuring the `rejected_msg` attribute. You will then receive a response like:
+
+```bash
+HTTP/1.1 503 Service Temporarily Unavailable
+Content-Type: text/html
+Content-Length: 194
+Connection: keep-alive
+Server: APISIX web server
+
+{"error_msg":"Requests are too frequent, please try again later."}
+```
## Disable Plugin
-When you want to disable the limit req 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-req` 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"],
@@ -230,9 +207,9 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-Remove the `limit-req` plugin on `consumer`.
+Similarly for removing the Plugin from a Consumer:
-```shell
+```bash
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"username": "consumer_jack",
@@ -243,5 +220,3 @@ curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f1
}
}'
```
-
-The limit req plugin has been disabled now. It works for other plugins.