cluster-key-rate-limit - API Gateway - Alibaba Cloud Documentation Center

The cluster-key-rate-limit plug-in implements cluster throttling based on Redis. This plug-in is suitable for scenarios where you need to implement global consistent throttling across multiple Higress Gateway instances. The keys used for throttling may be URL parameters, HTTP request headers, client IP addresses, consumer names, or keys in cookies.

Running attributes

Plug-in execution stage: default stage. Plug-in execution priority: 20.

Parameters

Field	Type	Required	Default value	Comment
rule_name	string	Yes	-	The name of the throttling rule. You can concatenate the throttling rule name, throttling type, throttling key name, and actual value of the throttling key into a Redis key.
rule_items	array of object	Yes	-	The items that are used to match a throttling rule based on the specified item sequence. If a throttling rule is matched based on an item, subsequent rules are skipped.
show_limit_quota_header	bool	No	false	Specifies whether to display the `X-RateLimit-Limit` (the total number of throttled requests) and `X-RateLimit-Remaining` (the number of remaining allowed requests) parameters in the response header.
rejected_code	int	No	429	The HTTP status code that is returned when requests are throttled.
rejected_msg	string	No	Too many requests	The body of the response that is returned when requests are throttled.
redis	object	Yes	-	The Redis-related configurations.

The following table describes the configuration fields in rule_items.

Field	Type	Required	Default value	Description
limit_by_header	string	No. You can configure only one of the `limit_by_*` fields.	-	The name of the HTTP request header that is used to obtain the key value for throttling.
limit_by_param	string	No. You can configure only one of the `limit_by_*` fields.	-	The name of the URL parameter that is used to obtain the key value for throttling.
limit_by_consumer	string	No. You can configure only one of the `limit_by_*` fields.	-	The name of the consumer that is used for throttling. You do not need to specify the actual value.
limit_by_cookie	string	No. You can configure only one of the `limit_by_*` fields.	-	The name of the cookie key that is used to obtain the key value for throttling.
limit_by_per_header	string	No. You can configure only one of the `limit_by_*` fields.	-	The names of the HTTP request headers that are used to obtain the key value for throttling. The system matches specific HTTP request headers based on rules and separately calculates the rate based on each request header. When you configure `limit_keys`, regular expressions or asterisks (`*`) are supported.
limit_by_per_param	string	No. You can configure only one of the `limit_by_*` fields.	-	The names of the URL parameters that are used to obtain the key value for throttling. The system matches specific URL parameters based on rules and separately calculates the rate based on each URL parameter. When you configure `limit_keys`, regular expressions or asterisks (`*`) are supported.
limit_by_per_consumer	string	No. You can configure only one of the `limit_by_*` fields.	-	The names of the consumers that are used to obtain the key value for rate limiting. The system matches specific consumers based on rules and separately calculates the rate based on each consumer. You do not need to specify the actual value. When you configure `limit_keys`, regular expressions or asterisks (`*`) are supported.
limit_by_per_cookie	string	No. You can configure only one of the `limit_by_*` fields.	-	The names of the cookie keys that are used to obtain the key value for rate limiting. The system matches specific cookie keys based on rules and separately calculates the rate based on each cookie key. When you configure `limit_keys`, regular expressions or asterisks (`*`) are supported.
limit_by_per_ip	string	No. You can configure only one of the `limit_by_*` fields.	-	The IP addresses that are used to obtain the key value for throttling. You can configure `from-header-Header name`, such as `from-header-x-forwarded-for`, to obtain IP addresses from request headers. You can also configure `from-remote-addr` to directly obtain the peer socket IP address. The system matches specific IP addresses based on rules and separately calculates the rate based on each IP address.
limit_keys	array of object	Yes.	-	The number of throttling times after the key value is matched.

The following table describes the configuration fields in limit_keys.

Field	Type	Required	Default value	Description
key	string	Yes.	-	The matched key value. Regular expressions or asterisks () are supported for `limit_by_per_header`, `limit_by_per_param`, `limit_by_per_consumer`, and `limit_by_per_cookie`. If you want to use a regular expression, you must place regexp: before the regular expression. If you use an asterisk (), all the key values are matched. Example of a regular expression: `regexp: ^d.*`. In this example, all strings that start with d can be matched. IP addresses or CIDR blocks are supported for `limit_by_per_ip`.
query_per_second	int	No. You can configure one of `query_per_second`, `query_per_minute`, `query_per_hour`, and `query_per_day`.	-	The number of requests that are allowed per second.
query_per_minute	int	No. You can configure one of `query_per_second`, `query_per_minute`, `query_per_hour`, and `query_per_day`.	-	The number of requests that are allowed per minute.
query_per_hour	int	No. You can configure one of `query_per_second`, `query_per_minute`, `query_per_hour`, and `query_per_day`.	-	The number of requests that are allowed per hour.
query_per_day	int	No. You can configure one of `query_per_second`, `query_per_minute`, `query_per_hour`, and `query_per_day`.	-	The number of requests that are allowed per day.

The following table describes the configuration fields in redis.

Field	Type	Required	Default value	Description
service_name	string	Yes	-	The Redis service name, which is a fully qualified domain name (FQDN) with a specific service type, such as my-redis.dns or redis.my-ns.svc.cluster.local.
service_port	int	No	If the service type is static service, the default value is 80. For other services, the default value is 6379.	The service port number of the Tair (Redis OSS-compatible) instance.
username	string	No	-	The Redis username.
password	string	No	-	The Redis password.
timeout	int	No	1000	The connection timeout period of the Tair (Redis OSS-compatible) instance. Unit: milliseconds.

Configuration examples

Identify requests based on the apikey parameter and perform different throttling operations for the requests

rule_name: default_rule
rule_items:
- limit_by_param: apikey
  limit_keys:
  - key: 9a342114-ba8a-11ec-b1bf-00163e1250b5
    query_per_minute: 10
  - key: a6a6d7f2-ba8a-11ec-bec2-00163e1250b5
    query_per_hour: 100
- limit_by_per_param: apikey
  limit_keys:
  # A regular expression is used to match all strings that start with a. For each request that matches the apikey parameter, 10 QDS is allowed.
  - key: "regexp:^a.*"
    query_per_second: 10
  # A regular expression is used to match all strings that start with b. For each request that matches the apikey parameter, 100 QD is allowed.
  - key: "regexp:^b.*"
    query_per_minute: 100
  # All requests are matched. For each request, 1,000 QDH is allowed.
  - key: "*"
    query_per_hour: 1000
redis:
  service_name: redis.static
show_limit_quota_header: true

Identify requests based on the request header x-ca-key and perform different throttling operations for the requests

rule_name: default_rule
rule_items:
- limit_by_header: x-ca-key
  limit_keys:
  - key: 102234
    query_per_minute: 10
  - key: 308239
    query_per_hour: 10
- limit_by_per_header: x-ca-key
  limit_keys:
  # A regular expression is used to match all strings that start with a. For each request that matches the apikey parameter, 10 QDS is allowed.
  - key: "regexp:^a.*"
    query_per_second: 10
  # A regular expression is used to match all strings that start with b. For each request that matches the apikey parameter, 100 QD is allowed.
  - key: "regexp:^b.*"
    query_per_minute: 100
  # All requests are matched. For each request, 1,000 QDH is allowed.
  - key: "*"
    query_per_hour: 1000
redis:
  service_name: redis.static
show_limit_quota_header: true

Obtain the peer IP addresses based on the request header x-forwarded-for and perform different throttling operations for requests

rule_name: default_rule
rule_items:
- limit_by_per_ip: from-header-x-forwarded-for
  limit_keys:
  # The exact IP address.
  - key: 1.1.1.1
    query_per_day: 10
  # The CIDR block. For each IP address in the CIDR block, 100 QPD is allowed.
  - key: 1.1.1.0/24
    query_per_day: 100
  # By default, 1,000 QPD is allowed for each IP address.
  - key: 0.0.0.0/0
    query_per_day: 1000
redis:
  service_name: redis.static
show_limit_quota_header: true

Identify requests based on consumers and perform different throttling operations for the requests

rule_name: default_rule
rule_items:
- limit_by_consumer: ''
  limit_keys:
  - key: consumer1
    query_per_second: 10
  - key: consumer2
    query_per_hour: 100
- limit_by_per_consumer: ''
  limit_keys:
  # A regular expression is used to match all strings that start with a. For each consumer that matches the apikey parameter, 10 QDS is allowed.
  - key: "regexp:^a.*"
    query_per_second: 10
  # A regular expression is used to match all strings that start with b. For each consumer that matches the apikey parameter, 100 QD is allowed.
  - key: "regexp:^b.*"
    query_per_minute: 100
  # All requests are matched. For each consumer, 1,000 QDH is allowed.
  - key: "*"
    query_per_hour: 1000
redis:
  service_name: redis.static
show_limit_quota_header: true

Identify requests based on key-value pairs in cookies and perform different throttling operations for the requests

rule_name: default_rule
rule_items:
  - limit_by_cookie: key1
    limit_keys:
      - key: value1
        query_per_minute: 10
      - key: value2
        query_per_hour: 100
  - limit_by_per_cookie: key1
    limit_keys:
      # A regular expression is used to match all strings that start with a. For each request that matches a specific cookie value, 10 QDS is allowed.
      - key: "regexp:^a.*"
        query_per_second: 10
      # A regular expression is used to match all strings that start with b. For each request that matches a specific cookie value, 100 QD is allowed.
      - key: "regexp:^b.*"
        query_per_minute: 100
      # All requests are matched. For each request, 1,000 QDH is allowed.
      - key: "*"
        query_per_hour: 1000
rejected_code: 200
rejected_msg: '{"code":-1,"msg":"Too many requests"}'
redis:
  service_name: redis.static
show_limit_quota_header: true