cluster-key-rate-limit-API Gateway(API Gateway)-阿里云帮助中心

The cluster-key-rate-limit plug-in enables Redis-based cluster rate limiting for globally consistent throttling across multiple Higress Gateway instances. Keys can be derived from URL parameters, HTTP request headers, client IP addresses, consumer names, or cookie keys.

Running attributes

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

Parameters

Field	Type	Required	Default value	Comment
rule_name	string	Yes	-	Throttling rule name. The rule name, throttling type, key name, and actual key value are concatenated to form the Redis key.
rule_items	array of object	Yes	-	Throttling rule items, evaluated in order. Once a match is found, subsequent items are skipped.
show_limit_quota_header	bool	No	false	Whether to include `X-RateLimit-Limit` (total throttled requests) and `X-RateLimit-Remaining` (remaining allowed requests) headers in the response.
rejected_code	int	No	429	HTTP status code returned when requests are throttled.
rejected_msg	string	No	Too many requests	Response body returned when requests are throttled.
redis	object	Yes	-	Redis connection settings.

The following table describes the 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.	-	HTTP request header name used as the throttling key.
limit_by_param	string	No. You can configure only one of the `limit_by_*` fields.	-	URL parameter name used as the throttling key.
limit_by_consumer	string	No. You can configure only one of the `limit_by_*` fields.	-	Consumer name used as the throttling key. No actual value is required.
limit_by_cookie	string	No. You can configure only one of the `limit_by_*` fields.	-	Cookie key name used as the throttling key.
limit_by_per_header	string	No. You can configure only one of the `limit_by_*` fields.	-	HTTP request header name for per-value throttling. Each distinct header value is rate-limited independently. Regular expressions and asterisks (`*`) are supported in `limit_keys`.
limit_by_per_param	string	No. You can configure only one of the `limit_by_*` fields.	-	URL parameter name for per-value throttling. Each distinct parameter value is rate-limited independently. Regular expressions and asterisks (`*`) are supported in `limit_keys`.
limit_by_per_consumer	string	No. You can configure only one of the `limit_by_*` fields.	-	Consumer name for per-consumer throttling. Each consumer is rate-limited independently. No actual value is required. Regular expressions and asterisks (`*`) are supported in `limit_keys`.
limit_by_per_cookie	string	No. You can configure only one of the `limit_by_*` fields.	-	Cookie key name for per-value throttling. Each distinct cookie value is rate-limited independently. Regular expressions and asterisks (`*`) are supported in `limit_keys`.
limit_by_per_ip	string	No. You can configure only one of the `limit_by_*` fields.	-	IP address source for per-IP throttling. Set to `from-header-<Header name>` (for example, `from-header-x-forwarded-for`) to extract IP addresses from a request header, or `from-remote-addr` to use the peer socket IP. Each IP address is rate-limited independently.
limit_keys	array of object	Yes.	-	Rate limit thresholds applied when a key value is matched.

The following table describes the fields in limit_keys.

Field	Type	Required	Default value	Description
key	string	Yes.	-	The key value to match. For `limit_by_per_header`, `limit_by_per_param`, `limit_by_per_consumer`, and `limit_by_per_cookie`, regular expressions (prefixed with `regexp:`) and asterisks () are supported. An asterisk matches all values. Example: `regexp: ^d.` matches all strings starting with d. For `limit_by_per_ip`, IP addresses and CIDR blocks are supported.
query_per_second	int	No. You can configure one of `query_per_second`, `query_per_minute`, `query_per_hour`, and `query_per_day`.	-	Allowed requests 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`.	-	Allowed requests 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`.	-	Allowed requests 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`.	-	Allowed requests per day.

The following table describes the fields in redis.

Field	Type	Required	Default value	Description
service_name	string	Yes	-	Redis service name as a fully qualified domain name (FQDN), 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.	Port number of the Tair (Redis OSS-compatible) instance.
username	string	No	-	Redis username.
password	string	No	-	Redis password.
timeout	int	No	1000	Connection timeout for the Tair (Redis OSS-compatible) instance, in 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