Docs
Plugin HubConfiguration Options

Parameters

See plugin common configurations (opens in Apache APISIX docs) for configuration options available to all plugins.

This plugin supports referencing sensitive parameter values from environment variables using the env:// prefix, or from a secret manager, such as HashiCorp Vault’s KV secrets engine, using the secret:// prefix. For more information, see environment variables in plugin (opens in Apache APISIX docs) and secrets (opens in Apache APISIX docs).

note

In API7 Enterprise (from 3.8.17), you should configure one of the following parameter sets, but not both:

  • count, time_window
  • rules

  • count

    integer | string

    required

    vaild vaule:

    greater than 0

    The maximum number of requests allowed within a given time interval.

    In API7 Enterprise (from 3.8.17), this parameter also supports the string data type and allows the use of built-in variables (opens in API7 Gateway docs) prefixed with a dollar sign ($).

  • time_window

    integer | string

    required

    vaild vaule:

    greater than 0

    The time interval corresponding to the rate limiting count in seconds.

    In API7 Enterprise (from 3.8.17), this parameter also supports the string data type and allows the use of built-in variables (opens in API7 Gateway docs) prefixed with a dollar sign ($).

  • window_type

    string

    default: fixed

    vaild vaule:

    fixed or sliding

    Rate limiting algorithm, fixed window or sliding window.

  • key_type

    string

    default: var

    vaild vaule:

    var, var_combination, or constant

    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.

    If the key_type is constant, the key is interpreted as a constant.

  • key

    string

    default: remote_addr

    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 API7 Gateway 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.

    If the key_type is constant, the key 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, or redis-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 is redis-sentinel.

  • redis_master_name

    string

    The name of the Redis master group that Sentinels are monitoring. Required when policy is redis-sentinel.

  • redis_role

    string

    default: master

    vaild vaule:

    master or slave

    The Redis node role to connect to. Configurable when policy is redis-sentinel. Set to master to connect to the current Redis master, and set to slave 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 is redis-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 is redis-sentinel.

  • sentinel_username

    string

    Username used to authenticate with the Redis Sentinel instance. Configurable when policy is redis-sentinel.

  • sentinel_password

    string

    Password used to authenticate with the Redis Sentinel instance. Configurable when policy is redis-sentinel.

  • allow_degradation

    boolean

    default: false

    If true, allow the gateway to continue handling requests without the plugin when the plugin or its dependencies become unavailable.

  • rules

    array[object]

    An array of rate-limiting rules that are applied sequentially.

    Available in API7 Enterprise from 3.8.17.

    • count

      integer | string

      required

      vaild vaule:

      greater than 0

      The maximum number of requests allowed within a given time interval.

      This parameter also supports the string data type and allows the use of built-in variables (opens in API7 Gateway docs) prefixed with a dollar sign ($).

    • time_window

      integer | string

      required

      vaild vaule:

      greater than 0

      The time interval corresponding to the rate limiting count in seconds.

      This parameter also supports the string data type and allows the use of built-in variables (opens in API7 Gateway docs) prefixed with a dollar sign ($).

    • key

      string

      required

      The key to count requests by. If the configured key does not exist, the rule will not be executed.

      The key is interpreted as a combination of variables, for example, $http_custom_a $http_custom_b.

    • header_prefix

      string

      Prefix for all rate limiting response headers. Available in API7 Enterprise from version 3.8.19.

      When configured, the prefix is inserted after X- in the header name. For example, with header_prefix set to test, the headers become X-Test-RateLimit-Limit, X-Test-RateLimit-Remaining, and X-Test-RateLimit-Reset.

      When not configured, the index of the rule in the rules array is used as the prefix. For example, headers for the first rule will be X-1-RateLimit-Limit, X-1-RateLimit-Remaining, and X-1-RateLimit-Reset.

  • show_limit_quota_header

    boolean

    default: true

    If true, includes the rate limiting response headers. Specifically, if rules is not set, the headers are:

    • X-RateLimit-Limit shows the total quota.
    • X-RateLimit-Remaining shows the remaining quota.
    • X-RateLimit-Reset shows the number of seconds until the counter resets.


    When rules is set, a prefix (followed by a hyphen) is inserted after X-. See rules.header_prefix for details.

  • group

    string

    vaild vaule:

    non-empty

    The group ID for the plugin, such that routes of the same group can share the same rate limiting counter.

  • redis_host

    string

    The address of the Redis node. Required when policy is redis.

  • redis_port

    integer

    default: 6379

    vaild vaule:

    greater than or equal to 1

    The port of the Redis node when policy is redis.

  • redis_username

    string

    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

    The password of the Redis node when policy is redis, or redis-cluster.

  • redis_database

    integer

    default: 0

    vaild vaule:

    greater than or equal to 0

    The database number in Redis when policy is redis or redis-sentinel.

  • redis_ssl

    boolean

    default: false

    If true, use SSL to connect to Redis when policy is redis.

  • redis_ssl_verify

    boolean

    default: false

    If true, verify the server SSL certificate when policy is redis.

  • redis_server_name

    string

    The server name (SNI) sent in the TLS handshake with Redis when policy is redis and redis_ssl is true. If unset, redis_host is sent, unless it is an IP address. Available in API7 Enterprise from version 3.9.21.

  • redis_timeout

    integer

    default: 1000

    vaild vaule:

    greater than or equal to 1

    The Redis timeout value in milliseconds when policy is redis or redis-cluster.

  • redis_keepalive_timeout

    integer

    vaild vaule:

    greater than or equal to 1000 for redis and redis-cluster; greater than or equal to 1 for redis-sentinel

    Time in milliseconds that an idle Redis connection is kept alive in the connection pool before being closed. When policy is redis or redis-cluster, the default is 10000. When policy is redis-sentinel, the default is 60000.

    For redis and redis-cluster, this parameter was introduced in API7 Enterprise 3.9.16 and 3.10.3.

  • redis_keepalive_pool

    integer

    default: 100

    vaild vaule:

    greater than or equal to 1

    Maximum number of idle Redis connections in the keepalive pool. Used when policy is redis or redis-cluster.

    Introduced in API7 Enterprise 3.9.16 and 3.10.3.

  • redis_cluster_nodes

    array[string]

    The list of 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 is redis-cluster.

  • redis_cluster_ssl

    boolean

    default: false

    If true, use SSL to connect to Redis cluster when policy is redis-cluster.

  • redis_cluster_ssl_verify

    boolean

    default: false

    If true, verify the server SSL certificate when policy is redis-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 than time_window. A value of 1 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.

Overview

Previous Page