Limit Conn Configuration
Configuration reference for the Limit Conn plugin (`limit-conn`): the parameters, each attribute with its type, whether it is required, its default and its accepted values.
Parameters
See plugin common configurations (opens in Apache APISIX docs) for configuration options available to all plugins.
In API7 Enterprise (from 3.8.17) and in APISIX (from 3.16.0), you should configure one of the following parameter sets, but not both:
conn,burst,default_conn_delay,keyrules,default_conn_delay
conn — integer | string · required · since APISIX 1.2
Valid values: greater than 0
The maximum number of concurrent requests allowed. Requests exceeding the configured limit and below conn + burst will be delayed.
A string value can reference a built-in variable (opens in Apache APISIX docs) by prefixing the variable name with a dollar sign ($). A resolved string must be a positive integer no greater than 9007199254740991. If resolution fails or produces an invalid value, the gateway returns 500 Internal Server Error unless degradation is enabled.
String-value support was introduced in API7 Enterprise 3.8.17 and APISIX 3.16.0. The validation requirements were introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.17.0. Earlier APISIX versions accept only integer values.
burst — integer | string · required · since APISIX 1.2
Valid values: greater than or equal to 0
The number of excessive concurrent requests allowed to be delayed. Requests exceeding conn + burst will be rejected immediately.
A string value can reference a built-in variable (opens in Apache APISIX docs) by prefixing the variable name with a dollar sign ($). A resolved string must be a non-negative integer no greater than 9007199254740991. If resolution fails or produces an invalid value, the gateway returns 500 Internal Server Error unless degradation is enabled.
String-value support was introduced in API7 Enterprise 3.8.17 and APISIX 3.16.0. The validation requirements were introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.17.0. Earlier APISIX versions accept only integer values.
default_conn_delay — number · required · since APISIX 1.2
Valid values: greater than 0
Processing latency allowed in seconds for concurrent requests exceeding conn and up to conn + burst, which can be dynamically adjusted based on only_use_default_delay setting.
only_use_default_delay — boolean · optional · default: false · since APISIX 2.8
If false, delay requests proportionally based on how much they exceed the conn limit. The delay grows larger as congestion increases. For instance, with conn being 5, burst being 3, and default_conn_delay being 1, 6 concurrent requests would result in a 1-second delay, 7 requests a 2-second delay, 8 requests a 3-second delay, and so on, until the total limit of conn + burst is reached, beyond which requests are rejected.
If true, use default_conn_delay to delay all excessive requests within the burst range. Requests beyond conn + burst are rejected immediately. For instance, with conn being 5, burst being 3, and default_conn_delay being 1, 6, 7, or 8 concurrent requests are all delayed by exactly 1 second each.
key_type — string · optional · default: var · since APISIX 2.11.0
Valid values: var or var_combination
The type of key.
If the key_type is var, the key is interpreted as a variable.
If the key_type is var_combination, the key is interpreted as a combination of variables.
key — string · required · since APISIX 1.2
The key to count requests by.
If the key_type is var, the key is interpreted as a variable. The variable does not need to be prefixed by a dollar sign ($). See built-in variables (opens in Apache APISIX docs) for available variables.
If the key_type is var_combination, the key is interpreted as a combination of variables. All variables should be prefixed by dollar signs ($). For example, to configure the key to use a combination of two request headers custom-a and custom-b, the key should be configured as $http_custom_a $http_custom_b.
rejected_code — integer · optional · default: 503 · since APISIX 1.2
Valid values: between 200 and 599 inclusive
The HTTP status code returned when a request is rejected for exceeding the threshold.
rejected_msg — string · optional · since APISIX 2.9
Valid values: any non-empty string
The response body returned when a request is rejected for exceeding the threshold.
allow_degradation — boolean · optional · default: false · since APISIX 2.9
If true, allow the gateway to continue handling requests without the plugin when the plugin or its dependencies become unavailable.
rules — array[object] · optional · since APISIX 3.14.0
An array of rate-limiting rules that are applied sequentially.
Rule support was introduced in API7 Enterprise 3.8.17 and APISIX 3.16.0.
conn — integer | string · required · since APISIX 3.16.0 · API7 Gateway 3.8.17
Valid values: greater than 0
The maximum number of concurrent requests allowed. Requests exceeding the configured limit and below conn + burst will be delayed.
A string value can reference a built-in variable (opens in Apache APISIX docs) by prefixing the variable name with a dollar sign ($). A resolved string must be a positive integer no greater than 9007199254740991.
String-value validation was introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.17.0.
burst — integer | string · required · since APISIX 3.16.0 · API7 Gateway 3.8.17
Valid values: greater than or equal to 0
The number of excessive concurrent requests allowed to be delayed. Requests exceeding conn + burst will be rejected immediately.
A string value can reference a built-in variable (opens in Apache APISIX docs) by prefixing the variable name with a dollar sign ($). A resolved string must be a non-negative integer no greater than 9007199254740991.
String-value validation was introduced in API7 Enterprise 3.9.14 and 3.10.1, and in APISIX 3.17.0.
key — string · required · since APISIX 3.16.0 · API7 Gateway 3.8.17
The key to count requests by. If the configured key does not exist, the rule will not be executed.
If the key_type is var, the key is interpreted as a variable. The variable does not need to be prefixed by a dollar sign ($). See built-in variables (opens in Apache APISIX docs) for available variables.
If the key_type is var_combination, the key is interpreted as a combination of variables. All variables should be prefixed by dollar signs ($). For example, to configure the key to use a combination of two request headers custom-a and custom-b, the key should be configured as $http_custom_a $http_custom_b.
policy — string · optional · default: local · since APISIX 3.9.0 · API7 Gateway 3.9.0
Valid values: local, redis, or redis-cluster
The policy for rate limiting counter. Required for API7 Enterprise (from 3.9.0) and optional for APISIX.
When set to local, the counter is stored in memory locally. When set to redis, the counter is stored on a Redis instance. When set to redis-cluster, the counter is stored in a Redis cluster.
redis_host — string · optional · since APISIX 3.9.0 · API7 Gateway 3.9.0
The address of the Redis node. Required when policy is redis.
redis_port — integer · optional · default: 6379 · since APISIX 3.9.0 · API7 Gateway 3.9.0
Valid values: greater than or equal to 1
The port of the Redis node when policy is redis.
redis_username — string · optional · since APISIX 3.9.0 · API7 Gateway 3.9.0
The username for Redis if Redis ACL is used. If you use the legacy authentication method requirepass, configure only the redis_password. Used when policy is redis.
redis_password — string · optional · since APISIX 3.9.0 · API7 Gateway 3.9.0
The password of the Redis node when policy is redis or redis-cluster. The password is encrypted at rest in API7 Enterprise. In APISIX, enable data encryption (opens in Apache APISIX docs) to encrypt it before etcd storage. Encryption was introduced in API7 Enterprise 3.9.16 and 3.10.2, and APISIX 3.18.0.
redis_database — integer · optional · default: 0 · since APISIX 3.9.0 · API7 Gateway 3.9.0
Valid values: greater than or equal to 0
The database number in Redis when policy is redis.
redis_ssl — boolean · optional · default: false · since APISIX 3.9.0 · API7 Gateway 3.9.0
If true, use SSL to connect to Redis when policy is redis.
redis_ssl_verify — boolean · optional · default: false · since APISIX 3.9.0 · API7 Gateway 3.9.0
If true, verify the server SSL certificate when policy is redis.
redis_timeout — integer · optional · default: 1000 · since APISIX 3.9.0 · API7 Gateway 3.9.0
Valid values: greater than or equal to 1
The Redis timeout value in milliseconds when policy is redis or redis-cluster.
redis_keepalive_timeout — integer · optional · default: 10000 · since APISIX 3.15.0 · API7 Gateway 3.9.17
Valid values: greater than or equal to 1000
Keepalive timeout in milliseconds for Redis when policy is redis or redis-cluster.
This parameter is available in API7 Enterprise from version 3.9.17 on the 3.9 line and from version 3.10.4 on the 3.10 line, and in APISIX from version 3.15.0.
redis_keepalive_pool — integer · optional · default: 100 · since APISIX 3.15.0 · API7 Gateway 3.9.17
Valid values: greater than or equal to 1
Keepalive pool size for Redis when policy is redis or redis-cluster.
This parameter is available in API7 Enterprise from version 3.9.17 on the 3.9 line and from version 3.10.4 on the 3.10 line, and in APISIX from version 3.15.0.
key_ttl — integer · optional · default: 3600
TTL of the Redis key in seconds when policy is redis or redis-cluster. Available in API7 Enterprise from version 3.9.4 and in APISIX from version 3.15.0.
redis_cluster_nodes — array[string] · optional · since APISIX 3.9.0 · API7 Gateway 3.9.0
The list of Redis cluster nodes with at least one address. Required when policy is redis-cluster.
redis_cluster_name — string · optional · since APISIX 3.9.0 · API7 Gateway 3.9.0
The name of the Redis cluster. Required when policy is redis-cluster.
redis_cluster_ssl — boolean · optional · default: false · since APISIX 3.9.0 · API7 Gateway 3.9.0
If true, use SSL to connect to Redis cluster when policy is redis-cluster.
redis_cluster_ssl_verify — boolean · optional · default: false · since APISIX 3.9.0 · API7 Gateway 3.9.0
If true, verify the server SSL certificate when policy is redis-cluster.