jiazhizhong/higress
1
0
Fork 0
mirror of https://github.com/alibaba/higress.git synced 2026-04-28 23:47:30 +08:00
Code Issues Packages Projects Releases Wiki Activity

update plugins doc (#1305)

Browse Source
This commit is contained in:
澄潭
2024-09-12 21:48:40 +08:00
committed by GitHub
parent 0f9113ed82
commit c7c4ae1da2
80 changed files with 7373 additions and 2368 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
plugins/wasm-cpp/extensions/key_rate_limit/README_EN.md
View File

@@ -1,31 +1,36 @@
<p>
English | <a href="README.md">中文</a>
</p>
---
title: Key-based Local Rate Limiting
keywords: [higress,key rate limit]
description: Configuration reference for Key local rate limiting plugin
---
# Description
`key-rate-limit` plugin implements a rate-limiting function based on specific key-values. The key-values may come from URL parameters or HTTP headers.
## Functional Description
The `key-rate-limit` plugin implements rate limiting based on specific key values, which can originate from URL parameters or HTTP request headers.
# Configuration Fields
## Running Properties
Plugin execution phase: `default phase`
Plugin execution priority: `10`
| Name | Type | Requirement | Default Value | Description |
| -------- | -------- | -------- | -------- | -------- |
| limit_by_header | string | Optional. Choose one from following: `limit_by_header`, `limit_by_param`. | - | The name of HTTP header used to obtain key-value used in rate-limiting. |
| limit_by_param | string | Optional. Choose one from following: `limit_by_header`, `limit_by_param`. | - | The name of URL parameter used to obtain key-value used in rate-limiting. |
| limit_keys | array of object | Required | - | Rate-limiting thresholds when matching specific key-values |
## Configuration Fields
Field descriptions of `limit_keys` items:
| Name | Data Type | Required | Default Value | Description |
|-----------------|-----------------|---------------------------------------------------------------|---------------|----------------------------------------------------------------------------------------|
| limit_by_header | string | Optional, choose one from `limit_by_header`, `limit_by_param` | - | Configuration for the source of the rate limiting key value (HTTP request header name) |
| limit_by_param | string | Optional, choose one from `limit_by_header`, `limit_by_param` | - | Configuration for the source of the rate limiting key value (URL parameter name) |
| limit_keys | array of object | Required | - | Configuration for the rate limiting frequency based on matched key values |
| Name | Type | Requirement | Default Value | Description |
| -------- | -------- | -------- | -------- | -------- |
| key | string | Required | - | Value to match of the specific key |
| query_per_second | number | Optional. Choose one from following: `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day`. | - | Number of requests allowed per second |
| query_per_minute | number | Optional. Choose one from following: `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day`. | - | Number of requests allowed per minute |
| query_per_hour | number | Optional. Choose one from following: `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day`. | - | Number of requests allowed per hour |
| query_per_day | number | Optional. Choose one from following: `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day`. | - | Number of requests allowed per day |
Explanation of each configuration field in `limit_keys`
# Configuration Samples
| Name | Data Type | Required | Default Value | Description |
|------------------|-----------|-----------------------------------------------------------------------------------------------------|---------------|---------------------------------------|
| key | string | Required | - | Matched key value |
| query_per_second | number | Optional, choose one from `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day` | - | Allowed number of requests per second |
| query_per_minute | number | Optional, choose one from `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day` | - | Allowed number of requests per minute |
| query_per_hour | number | Optional, choose one from `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day` | - | Allowed number of requests per hour |
| query_per_day | number | Optional, choose one from `query_per_second`, `query_per_minute`, `query_per_hour`, `query_per_day` | - | Allowed number of requests per day |
## Use query parameter `apikey` for rate-limiting
## Configuration Examples
### Identify request parameter apikey for differentiated rate limiting
```yaml
limit_by_param: apikey
limit_keys:
@@ -35,7 +40,7 @@ limit_keys:
query_per_minute: 100
```
## Use HTTP header parameter `x-ca-key` for rate-limiting
### Identify request header x-ca-key for differentiated rate limiting
```yaml
limit_by_header: x-ca-key
limit_keys:
@@ -44,28 +49,3 @@ limit_keys:
- key: 308239
query_per_hour: 10
```
## Enable rate-limiting for specific routes or domains
```yaml
# Use _rules_ field for fine-grained rule configurations
_rules_:
# Rule 1: Match by route name
- _match_route_:
- route-a
- route-b
limit_by_header: x-ca-key
limit_keys:
- key: 102234
query_per_second: 10
# Rule 2: Match by domain
- _match_domain_:
- "*.example.com"
- test.com
limit_by_header: x-ca-key
limit_keys:
- key: 102234
query_per_second: 100
```
In the rule sample of `_match_route_`, `route-a` and `route-b` are the route names provided when creating a new gateway route. When the current route names matches the configuration, the rule following shall be applied.
In the rule sample of `_match_domain_`, `*.example.com` and `test.com` are the domain names used for request matching. When the current domain name matches the configuration, the rule following shall be applied.
All rules shall be checked following the order of items in the `_rules_` field, The first matched rule will be applied. All remained will be ignored.