Parameters
See plugin common configurations for configuration options available to all plugins.
All parameters can be configured using environment variables. For example, you can save Redis password to an environment variable REDIS_PASSWORD
and configure redis_password
to be $env://REDIS_PASSWORD
.
count
integer
required
vaild vaule:
greater than 0
The maximum number of requests allowed within a given time interval.
time_window
integer
required
vaild vaule:
greater than 0
The time interval corresponding to the rate limiting
count
in seconds.window_type
string
default:
fixed
vaild vaule:
fixed
orsliding
Rate limiting algorithm, fixed window or sliding window.
key_type
string
default:
var
vaild vaule:
var
,var_combination
, orconstant
The type of key.
If the
key_type
isvar
, thekey
is interpreted a variable.If the
key_type
isvar_combination
, thekey
is interpreted as a combination of variables.If the
key_type
isconstant
, thekey
is interpreted as a constant.key
string
default:
remote_addr
The key to count requests by.
If the
key_type
isvar
, thekey
is interpreted a variable. The variable does not need to be prefixed by a dollar sign ($
). See built-in variables for avaialble variables.If the
key_type
isvar_combination
, thekey
is interpreted as a combination of variables. All variables should be prefixed by dollar signs ($
). For example, to configure thekey
to use a combination of two request headerscustom-a
andcustom-b
, thekey
should be configured as$http_custom_a $http_custom_b
.If the
key_type
isconstant
, thekey
is interpreted as a constant value.rejected_code
integer
default:
503
vaild vaule:
between 200 and 599 inclusive
The HTTP status code returned when a request is rejected for exceeding the threshold.
rejected_msg
string
vaild vaule:
any non-empty string
The response body returned when a request is rejected for exceeding the threshold.
policy
string
default:
local
vaild vaule:
local
,redis
,redis-cluster
, orredis-sentinel
The policy for rate limiting counter.
Set to
local
to store the counter in memory locally.Set to
redis
to store the counter on a Redis instance.Set to
redis-cluster
to store the counter in a Redis cluster.Set to
redis-sentinel
to store the counter on the Redis primary node managed by Redis Sentinel, which ensures high availability by automatically promoting a replica to primary in case of failure. Redis Sentinel provides high availability for Redis when not using Redis Cluster.redis_sentinels
array[object]
An array of Redis Sentinel nodes (host and port). Required when
policy
isredis-sentinel
.redis_master_name
string
The name of the Redis master group that Sentinels are monitoring. Required when
policy
isredis-sentinel
.redis_role
string
default:
master
vaild vaule:
master
orslave
The Redis node role to connect to. Configurable when
policy
isredis-sentinel
. Set tomaster
to connect to the current Redis master, and set toslave
to connect to a Redis replica.redis_connect_timeout
integer
default:
1000
vaild vaule:
greater than or equal to 1
Timeout in milliseconds for establishing a connection to a Redis node. Configurable when
policy
isredis-sentinel
.redis_read_timeout
integer
default:
1000
vaild vaule:
greater than or equal to 1
Timeout in milliseconds for reading data from a Redis node. Configurable when
policy
isredis-sentinel
.redis_keepalive_timeout
integer
default:
60000
vaild vaule:
greater than or equal to 1
Time in milliseconds that an idle Redis connection is kept alive in the connection pool before being closed. Configurable when
policy
isredis-sentinel
.sentinel_username
string
Username used to authenticate with the Redis Sentinel instance.
sentinel_password
string
Password used to authenticate with the Redis Sentinel instance.
allow_degradation
boolean
default:
false
If true, allow APISIX to continue handling requests without the plugin when the plugin or its dependencies become unavailable.
show_limit_quota_header
boolean
default:
true
If true, include
X-RateLimit-Limit
to show the total quota andX-RateLimit-Remaining
to show the remaining quota in the response header.group
string
vaild vaule:
non-empty
The
group
ID for the plugin, such that routes of the samegroup
can share the same rate limiting counter.redis_host
string
The address of the Redis node. Required when
policy
isredis
.redis_port
integer
default:
6379
vaild vaule:
greater than or equal to 1
The port of the Redis node when
policy
isredis
.redis_username
string
The username for Redis if Redis ACL is used. If you use the legacy authentication method
requirepass
, configure only theredis_password
. Used whenpolicy
isredis
.redis_password
string
default:
6379
The password of the Redis node when
policy
isredis
, orredis-cluster
.redis_database
integer
default:
0
vaild vaule:
greater than or equal to 0
The database number in Redis when
policy
isredis
orredis-sentinel
.redis_ssl
boolean
default:
false
If true, use SSL to connect to Redis cluster when
policy
isredis
.redis_ssl_verify
boolean
default:
false
If true, verify the server SSL certificate when
policy
isredis
.redis_timeout
integer
default:
1000
vaild vaule:
greater than or equal to 1
The Redis timeout value in milliseconds when
policy
isredis
orredis-cluster
.redis_cluster_nodes
array[string]
The list of the Redis cluster nodes with at least two addresses. Required when policy is redis-cluster.
redis_cluster_name
string
The name of the Redis cluster. Required when
policy
isredis-cluster
.redis_cluster_ssl
boolean
default:
false
If true, use SSL to connect to Redis cluster when
policy
isredis-cluster
.redis_cluster_ssl_verify
boolean
default:
false
If true, verify the server SSL certificate when
policy
isredis-cluster
.sync_interval
number
default:
-1
vaild vaule:
greater than or equal to 0.1, or the default -1
The frequency of synchronizing counter data to Redis. Available only in Enterprise.
The
sync_interval
value should be smaller thantime_window
. A value of1
results in synchronizing counter data every second. A value of-1
yields no change in synchronizing behaviour, i.e. counter data will be synchronized for each request.