Function Description

The cluster-key-rate-limit plugin implements cluster rate limiting based on Redis, suitable for scenarios that require global consistent rate limiting across multiple Higress Gateway instances.

The Key used for rate limiting can originate from URL parameters, HTTP request headers, client IP addresses, consumer names, or keys in cookies.

Execution Attributes

Plugin Execution Phase: default phase
Plugin Execution Priority: 20

Configuration Description

Configuration ItemTypeRequiredDefault ValueDescription
rule_namestringYes-The name of the rate limiting rule. The Redis key is constructed using rule name + rate limit type + limit key name + actual value of the limit key.
rule_itemsarray of objectYes-Rate limiting rule items. The first matching rule_item based on the order under rule_items will trigger the rate limiting, and subsequent rules will be ignored.
show_limit_quota_headerboolNofalseWhether to display X-RateLimit-Limit (total requests allowed) and X-RateLimit-Remaining (remaining requests that can be sent) in the response headers.
rejected_codeintNo429HTTP status code returned when a request is rate limited.
rejected_msgstringNoToo many requestsResponse body returned when a request is rate limited.
redisobjectYes-Redis related configuration.

Description of configuration fields for each item in rule_items.

Configuration ItemTypeRequiredDefault ValueDescription
limitby_headerstringNo, one of limit_by-The name of the HTTP request header from which to retrieve the rate limiting key value.
limitby_paramstringNo, one of limit_by-The name of the URL parameter from which to retrieve the rate limiting key value.
limitby_consumerstringNo, one of limit_by-Applies rate limiting based on consumer name without needing to add an actual value.
limitby_cookiestringNo, one of limit_by-The name of the key in the Cookie from which to retrieve the rate limiting key value.
limitby_per_headerstringNo, one of limit_by-Matches specific HTTP request headers according to the rules and calculates rate limits for each header. The limit_keys configuration supports regular expressions or .
limitby_per_paramstringNo, one of limit_by-Matches specific URL parameters according to the rules and calculates rate limits for each parameter. The limit_keys configuration supports regular expressions or .
limitby_per_consumerstringNo, one of limit_by-Matches specific consumers according to the rules and calculates rate limits for each consumer. The limit_keys configuration supports regular expressions or .
limitby_per_cookiestringNo, one of limit_by-Matches specific cookies according to the rules and calculates rate limits for each cookie. The limit_keys configuration supports regular expressions or .
limitby_per_ipstringNo, one of limit_by*-Matches specific IPs according to the rules and calculates rate limits for each IP. Retrieve via IP parameter name from request headers, defined as from-header-{header name}, e.g., from-header-x-forwarded-for. To get the remote socket IP directly, use from-remote-addr.
limit_keysarray of objectYes-Configures the limit counts after matching key values.

Description of configuration fields for each item in limit_keys.

Configuration ItemTypeRequiredDefault ValueDescription
keystringYes-Matched key value; types limit_by_per_header, limit_by_per_param, limit_by_per_consumer, limit_by_per_cookie support regular expression configurations (starting with regexp: followed by a regular expression) or (representing all), e.g., regexp:^d. (all strings starting with d); limit_by_per_ip supports configuring IP addresses or IP segments.
query_per_secondintNo, one of query_per_second, query_per_minute, query_per_hour, query_per_day is optional.-Allowed number of requests per second.
query_per_minuteintNo, one of query_per_second, query_per_minute, query_per_hour, query_per_day is optional.-Allowed number of requests per minute.
query_per_hourintNo, one of query_per_second, query_per_minute, query_per_hour, query_per_day is optional.-Allowed number of requests per hour.
query_per_dayintNo, one of query_per_second, query_per_minute, query_per_hour, query_per_day is optional.-Allowed number of requests per day.

Description of configuration fields for each item in redis.

Configuration ItemTypeRequiredDefault ValueDescription
service_namestringRequired-Full FQDN name of the Redis service, including service type, e.g., my-redis.dns, redis.my-ns.svc.cluster.local.
service_portintNo80 for static services; otherwise 6379Service port for the Redis service.
usernamestringNo-Redis username.
passwordstringNo-Redis password.
timeoutintNo1000Redis connection timeout in milliseconds.

Configuration Examples

Distinguish rate limiting based on the request parameter apikey

  1. rule_name: default_rule
  2. rule_items:
  3. - limit_by_param: apikey
  4.   limit_keys:
  5.   - key: 9a342114-ba8a-11ec-b1bf-00163e1250b5
  6.     query_per_minute: 10
  7.   - key: a6a6d7f2-ba8a-11ec-bec2-00163e1250b5
  8.     query_per_hour: 100
  9. - limit_by_per_param: apikey
  10.   limit_keys:
  11.   # Regular expression, matches all strings starting with a, each apikey corresponds to 10qds.
  12.   - key: “regexp:^a.“
  13.     query_per_second: 10
  14.   # Regular expression, matches all strings starting with b, each apikey corresponds to 100qd.
  15.   - key: “regexp:^b.“
  16.     query_per_minute: 100
  17.   # As a fallback, matches all requests, each apikey corresponds to 1000qdh.
  18.   - key: “*”
  19.     query_per_hour: 1000
  20. redis:
  21.   service_name: redis.static
  22. show_limit_quota_header: true

Distinguish rate limiting based on the header x-ca-key

  1. rule_name: default_rule
  2. rule_items:
  3. - limit_by_header: x-ca-key
  4.   limit_keys:
  5.   - key: 102234
  6.     query_per_minute: 10
  7.   - key: 308239
  8.     query_per_hour: 10
  9. - limit_by_per_header: x-ca-key
  10.   limit_keys:
  11.   # Regular expression, matches all strings starting with a, each apikey corresponds to 10qds.
  12.   - key: “regexp:^a.“
  13.     query_per_second: 10
  14.   # Regular expression, matches all strings starting with b, each apikey corresponds to 100qd.
  15.   - key: “regexp:^b.“
  16.     query_per_minute: 100
  17.   # As a fallback, matches all requests, each apikey corresponds to 1000qdh.
  18.   - key: “*”
  19.     query_per_hour: 1000
  20. redis:
  21.   service_name: redis.static
  22. show_limit_quota_header: true

Distinguish rate limiting based on the client IP from the request header x-forwarded-for

  1. rule_name: default_rule
  2. rule_items:
  3. - limit_by_per_ip: from-header-x-forwarded-for
  4.   limit_keys:
  5.   # Exact IP
  6.   - key: 1.1.1.1
  7.     query_per_day: 10
  8.   # IP segment, for IPs matching this segment, each IP corresponds to 100qpd.
  9.   - key: 1.1.1.0/24
  10.     query_per_day: 100
  11.   # As a fallback, defaults to 1000 qpd for each IP.
  12.   - key: 0.0.0.0/0
  13.     query_per_day: 1000
  14. redis:
  15.   service_name: redis.static
  16. show_limit_quota_header: true

Distinguish rate limiting based on consumers

  1. rule_name: default_rule
  2. rule_items:
  3. - limit_by_consumer: ‘’
  4.   limit_keys:
  5.   - key: consumer1
  6.     query_per_second: 10
  7.   - key: consumer2
  8.     query_per_hour: 100
  9. - limit_by_per_consumer: ‘’
  10.   limit_keys:
  11.   # Regular expression, matches all strings starting with a, each consumer corresponds to 10qds.
  12.   - key: “regexp:^a.“
  13.     query_per_second: 10
  14.   # Regular expression, matches all strings starting with b, each consumer corresponds to 100qd.
  15.   - key: “regexp:^b.“
  16.     query_per_minute: 100
  17.   # As a fallback, matches all requests, each consumer corresponds to 1000qdh.
  18.   - key: “*”
  19.     query_per_hour: 1000
  20. redis:
  21.   service_name: redis.static
  22. show_limit_quota_header: true

Distinguish rate limiting based on key-value pairs in cookies

  1. rule_name: default_rule
  2. rule_items:
  3.   - limit_by_cookie: key1
  4.     limit_keys:
  5.       - key: value1
  6.         query_per_minute: 10
  7.       - key: value2
  8.         query_per_hour: 100
  9.   - limit_by_per_cookie: key1
  10.     limit_keys:
  11.       # Regular expression, matches all strings starting with a, each cookie’s value corresponds to 10qds.
  12.       - key: “regexp:^a.“
  13.         query_per_second: 10
  14.       # Regular expression, matches all strings starting with b, each cookie’s value corresponds to 100qd.
  15.       - key: “regexp:^b.“
  16.         query_per_minute: 100
  17.       # As a fallback, matches all requests, each cookie’s value corresponds to 1000qdh.
  18.       - key: “*”
  19.         query_per_hour: 1000
  20. rejected_code: 200
  21. rejected_msg: ‘{“code”:-1,”msg”:”Too many requests”}’
  22. redis:
  23.   service_name: redis.static
  24. show_limit_quota_header: true