feat(translator): implement ratelimit costs

Signed-off-by: Takeshi Yoneda <[email protected]>
envoyproxy · Jan 11, 2025 · f3e2036 · f3e2036
1 parent 88f3461
commit f3e2036
Show file tree

Hide file tree

Showing 6 changed files with 48 additions and 5 deletions.
diff --git a/api/v1alpha1/ratelimit_types.go b/api/v1alpha1/ratelimit_types.go
@@ -98,7 +98,6 @@ type RateLimitRule struct {
 	// the request path and do not reduce the rate limit counters on the response path.
 	//
 	// +optional
-	// +notImplementedHide
 	Cost *RateLimitCost `json:"cost,omitempty"`
 }
 
@@ -112,7 +111,6 @@ type RateLimitCost struct {
 	// enough capacity, the request is rate limited.
 	//
 	// +optional
-	// +notImplementedHide
 	Request *RateLimitCostSpecifier `json:"request,omitempty"`
 	// Response specifies the number to reduce the rate limit counters
 	// after the response is sent back to the client or the request stream is closed.
@@ -127,7 +125,6 @@ type RateLimitCost struct {
 	// Currently, this is only supported for HTTP Global Rate Limits.
 	//
 	// +optional
-	// +notImplementedHide
 	Response *RateLimitCostSpecifier `json:"response,omitempty"`
 }
 
@@ -143,12 +140,10 @@ type RateLimitCostSpecifier struct {
 	// Using zero can be used to only check the rate limit counters without reducing them.
 	//
 	// +optional
-	// +notImplementedHide
 	Number *uint64 `json:"number,omitempty"`
 	// Metadata specifies the per-request metadata to retrieve the usage number from.
 	//
 	// +optional
-	// +notImplementedHide
 	Metadata *RateLimitCostMetadata `json:"metadata,omitempty"`
 }
 

diff --git a/internal/ir/xds.go b/internal/ir/xds.go
@@ -1878,6 +1878,8 @@ type RateLimitRule struct {
 	ResponseCost *RateLimitCost `json:"responseCost,omitempty" yaml:"responseCost,omitempty"`
 }
 
+// RateLimitCost specifies the cost of the request or response.
+// +k8s:deepcopy-gen=true
 type RateLimitCost struct {
 	Number *uint64 `json:"number,omitempty" yaml:"number,omitempty"`
 	Format *string `json:"format,omitempty" yaml:"format,omitempty"`

diff --git a/internal/ir/zz_generated.deepcopy.go b/internal/ir/zz_generated.deepcopy.go
diff --git a/release-notes/current.yaml b/release-notes/current.yaml
@@ -20,6 +20,7 @@ new features: |
   Added support for patching EnvoyProxy.spec.provider.kubernetes.envoyHpa and EnvoyProxy.spec.provider.kubernetes.envoyPDB
   Added support for defining rateLimitHpa in EnvoyGateway API
   Added support for preserving the user defined HTTPRoute match order in EnvoyProxy API
+  Added support for cost specifier in the rate limit API.
 
 bug fixes: |
   Fixed a nil pointer error that occurs when a SecurityPolicy refers to a UDS backend

diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md
@@ -3388,6 +3388,8 @@ _Appears in:_
 
 | Field | Type | Required | Description |
 | ---   | ---  | ---      | ---         |
+| `request` | _[RateLimitCostSpecifier](#ratelimitcostspecifier)_ |  false  | Request specifies the number to reduce the rate limit counters<br />on the request path. If this is not specified, the default behavior<br />is to reduce the rate limit counters by 1.<br /><br />When Envoy receives a request that matches the rule, it tries to reduce the<br />rate limit counters by the specified number. If the counter doesn't have<br />enough capacity, the request is rate limited. |
+| `response` | _[RateLimitCostSpecifier](#ratelimitcostspecifier)_ |  false  | Response specifies the number to reduce the rate limit counters<br />after the response is sent back to the client or the request stream is closed.<br /><br />The cost is used to reduce the rate limit counters for the matching requests.<br />Since the reduction happens after the request stream is complete, the rate limit<br />won't be enforced for the current request, but for the subsequent matching requests.<br /><br />This is optional and if not specified, the rate limit counters are not reduced<br />on the response path.<br /><br />Currently, this is only supported for HTTP Global Rate Limits. |
 
 
 #### RateLimitCostFrom
@@ -3433,6 +3435,8 @@ _Appears in:_
 | Field | Type | Required | Description |
 | ---   | ---  | ---      | ---         |
 | `from` | _[RateLimitCostFrom](#ratelimitcostfrom)_ |  true  | From specifies where to get the rate limit cost. Currently, only "Number" and "Metadata" are supported. |
+| `number` | _integer_ |  false  | Number specifies the fixed usage number to reduce the rate limit counters.<br />Using zero can be used to only check the rate limit counters without reducing them. |
+| `metadata` | _[RateLimitCostMetadata](#ratelimitcostmetadata)_ |  false  | Refer to Kubernetes API documentation for fields of `metadata`. |
 
 
 #### RateLimitDatabaseBackend
@@ -3524,6 +3528,7 @@ _Appears in:_
 | ---   | ---  | ---      | ---         |
 | `clientSelectors` | _[RateLimitSelectCondition](#ratelimitselectcondition) array_ |  false  | ClientSelectors holds the list of select conditions to select<br />specific clients using attributes from the traffic flow.<br />All individual select conditions must hold True for this rule<br />and its limit to be applied.<br /><br />If no client selectors are specified, the rule applies to all traffic of<br />the targeted Route.<br /><br />If the policy targets a Gateway, the rule applies to each Route of the Gateway.<br />Please note that each Route has its own rate limit counters. For example,<br />if a Gateway has two Routes, and the policy has a rule with limit 10rps,<br />each Route will have its own 10rps limit. |
 | `limit` | _[RateLimitValue](#ratelimitvalue)_ |  true  | Limit holds the rate limit values.<br />This limit is applied for traffic flows when the selectors<br />compute to True, causing the request to be counted towards the limit.<br />The limit is enforced and the request is ratelimited, i.e. a response with<br />429 HTTP status code is sent back to the client when<br />the selected requests have reached the limit. |
+| `cost` | _[RateLimitCost](#ratelimitcost)_ |  false  | Cost specifies the cost of requests and responses for the rule.<br /><br />This is optional and if not specified, the default behavior is to reduce the rate limit counters by 1 on<br />the request path and do not reduce the rate limit counters on the response path. |
 
 
 #### RateLimitSelectCondition

diff --git a/site/content/zh/latest/api/extension_types.md b/site/content/zh/latest/api/extension_types.md
@@ -3388,6 +3388,8 @@ _Appears in:_
 
 | Field | Type | Required | Description |
 | ---   | ---  | ---      | ---         |
+| `request` | _[RateLimitCostSpecifier](#ratelimitcostspecifier)_ |  false  | Request specifies the number to reduce the rate limit counters<br />on the request path. If this is not specified, the default behavior<br />is to reduce the rate limit counters by 1.<br /><br />When Envoy receives a request that matches the rule, it tries to reduce the<br />rate limit counters by the specified number. If the counter doesn't have<br />enough capacity, the request is rate limited. |
+| `response` | _[RateLimitCostSpecifier](#ratelimitcostspecifier)_ |  false  | Response specifies the number to reduce the rate limit counters<br />after the response is sent back to the client or the request stream is closed.<br /><br />The cost is used to reduce the rate limit counters for the matching requests.<br />Since the reduction happens after the request stream is complete, the rate limit<br />won't be enforced for the current request, but for the subsequent matching requests.<br /><br />This is optional and if not specified, the rate limit counters are not reduced<br />on the response path.<br /><br />Currently, this is only supported for HTTP Global Rate Limits. |
 
 
 #### RateLimitCostFrom
@@ -3433,6 +3435,8 @@ _Appears in:_
 | Field | Type | Required | Description |
 | ---   | ---  | ---      | ---         |
 | `from` | _[RateLimitCostFrom](#ratelimitcostfrom)_ |  true  | From specifies where to get the rate limit cost. Currently, only "Number" and "Metadata" are supported. |
+| `number` | _integer_ |  false  | Number specifies the fixed usage number to reduce the rate limit counters.<br />Using zero can be used to only check the rate limit counters without reducing them. |
+| `metadata` | _[RateLimitCostMetadata](#ratelimitcostmetadata)_ |  false  | Refer to Kubernetes API documentation for fields of `metadata`. |
 
 
 #### RateLimitDatabaseBackend
@@ -3524,6 +3528,7 @@ _Appears in:_
 | ---   | ---  | ---      | ---         |
 | `clientSelectors` | _[RateLimitSelectCondition](#ratelimitselectcondition) array_ |  false  | ClientSelectors holds the list of select conditions to select<br />specific clients using attributes from the traffic flow.<br />All individual select conditions must hold True for this rule<br />and its limit to be applied.<br /><br />If no client selectors are specified, the rule applies to all traffic of<br />the targeted Route.<br /><br />If the policy targets a Gateway, the rule applies to each Route of the Gateway.<br />Please note that each Route has its own rate limit counters. For example,<br />if a Gateway has two Routes, and the policy has a rule with limit 10rps,<br />each Route will have its own 10rps limit. |
 | `limit` | _[RateLimitValue](#ratelimitvalue)_ |  true  | Limit holds the rate limit values.<br />This limit is applied for traffic flows when the selectors<br />compute to True, causing the request to be counted towards the limit.<br />The limit is enforced and the request is ratelimited, i.e. a response with<br />429 HTTP status code is sent back to the client when<br />the selected requests have reached the limit. |
+| `cost` | _[RateLimitCost](#ratelimitcost)_ |  false  | Cost specifies the cost of requests and responses for the rule.<br /><br />This is optional and if not specified, the default behavior is to reduce the rate limit counters by 1 on<br />the request path and do not reduce the rate limit counters on the response path. |
 
 
 #### RateLimitSelectCondition