cluster-key-rate-limit - Microservices Engine - Alibaba Cloud Documentation Center

The cluster-key-rate-limit plug-in implements rate limiting in a cluster based on Redis. This plug-in is suitable for scenarios where you need to implement a global consistent rate limiting across multiple Higress gateways. The keys that are used for rate limiting can be sourced 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.

Fields

Field	Type	Required	Default value	Description
rule_name	string	Yes	-	The name of the rate limiting rule. You can concatenate the rate limiting rule name, rate limiting type, rate limiting key name, and actual value of the rate limiting key into a Redis key.
rule_items	array of object	Yes	-	The items that are used to match a rate limiting rule based on the specified item sequence. If a rate limiting rule is matched based on an item, subsequent rules are skipped.
show_limit_quota_header	bool	No	false	Specifies whether to display `X-RateLimit-Limit` and `X-RateLimit-Remaining`. X-RateLimit-Limit specifies the maximum total number of requests. X-RateLimit-Remaining specifies the maximum number of remaining requests that can be sent.
rejected_code	int	No	429	The HTTP status code that is returned during rate limiting.
rejected_msg	string	No	Too many requests	The body of the response that is returned during rate limiting.
redis	object	Yes	-	The Redis-related configuration.

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.	-	The name of the HTTP request header that is used to obtain the key value for rate limiting.
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 rate limiting.
limit_by_consumer	string	No. You can configure only one of the `limit_by_*` fields.	-	The name of the consumer that is used for rate limiting. 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 rate limiting.
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 rate limiting. 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 rate limiting. 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 rate limiting. 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 times rate limiting is triggered after the key value is matched.

The following table describes the 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 only one of the `query_per_second`, `query_per_minute`, `query_per_hour`, and `query_per_day` fields.	-	The number of requests that are allowed per second.
query_per_minute	int	No. You can configure only one of the `query_per_second`, `query_per_minute`, `query_per_hour`, and `query_per_day` fields.	-	The number of requests that are allowed per minute.
query_per_hour	int	No. You can configure only one of the `query_per_second`, `query_per_minute`, `query_per_hour`, and `query_per_day` fields.	-	The number of requests that are allowed per hour.
query_per_day	int	No. You can configure only one of the `query_per_second`, `query_per_minute`, `query_per_hour`, and `query_per_day` fields.	-	The number of requests that are allowed per day.

The following table describes the fields in redis.

Field	Type	Required	Default value	Description
service_name	string	Required	-	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 Redis instance.
username	string	No	-	The username that is used to log on to the Redis instance.
password	string	No	-	The password that is used to log on to the Redis instance.
timeout	int	No	1000	The connection timeout period of the Redis instance. Unit: milliseconds.

Configuration examples

Identify requests based on the apikey parameter and perform different rate limiting 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 rate limiting 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 rate limiting operations for requests.

rule_name: default_rule
rule_items:
- limit_by_per_ip: from-header-x-forwarded-for
  limit_keys:
  # An exact IP address is used to match requests.
  - key: 1.1.1.1
    query_per_day: 10
  # A CIDR block is used to match requests. For each IP address in the CIDR block, 100 QPD is allowed.
  - key: 1.1.1.0/24
    query_per_day: 100
  # All requests are matched. For each request, 1,000 QPD is allowed by default.
  - 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 rate limiting 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 requests of 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 rate limiting 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