Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

api: adds hits_addend specifier to RateLimitRule #4957

Open
wants to merge 9 commits into
base: main
Choose a base branch
from
Open

api: adds hits_addend specifier to RateLimitRule #4957

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
46b1df8
api: usage based rate limit API support
mathetake Dec 20, 2024
0ae9d3f
more
mathetake Dec 20, 2024
598f6e5
gen
mathetake Dec 20, 2024
682caf9
modifies the comments
mathetake Dec 23, 2024
6303d3a
cel validations and tests
mathetake Dec 23, 2024
d5fbb21
more
mathetake Dec 23, 2024
f6b521d
more on the doc
mathetake Dec 23, 2024
a447e40
removes implementation-hide
mathetake Dec 27, 2024
d1b3de3
hide
mathetake Dec 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 59 additions & 0 deletions api/v1alpha1/ratelimit_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ type LocalRateLimit struct {
//
// +optional
// +kubebuilder:validation:MaxItems=16
// +kubebuilder:validation:XValidation:rule="self.all(foo, !has(foo.responseHitsAddend))", message="responseHitsAddend is not supported for Local Rate Limits"
Rules []RateLimitRule `json:"rules"`
}

Expand Down Expand Up @@ -91,6 +92,64 @@ type RateLimitRule struct {
// 429 HTTP status code is sent back to the client when
// the selected requests have reached the limit.
Limit RateLimitValue `json:"limit"`
// RequestHitsAddend specifies the number to reduce the rate limit counters
// on the request path. If the addend is not specified, the default behavior
// is to reduce the rate limit counters by 1.
//
// When Envoy receives a request that matches the rule, it tries to reduce the
// rate limit counters by the specified number. If the counter doesn't have
// enough capacity, the request is rate limited.
//
// +optional
// +notImplementedHide
RequestHitsAddend *RateLimitHitsAddend `json:"requestHitsAddend,omitempty"`
// ResponseHitsAddend specifies the number to reduce the rate limit counters
// after the response is sent back to the client or the request stream is closed.
//
// The addend is used to reduce the rate limit counters for the matching requests.
// Since the reduction happens after the request stream is complete, the rate limit
// won't be enforced for the current request, but for the subsequent matching requests.
//
// This is optional and if not specified, the rate limit counters are not reduced
// on the response path.
//
// Currently, this is only supported for HTTP Global Rate Limits.
mathetake marked this conversation as resolved.
Show resolved Hide resolved
//
// +optional
// +notImplementedHide
ResponseHitsAddend *RateLimitHitsAddend `json:"responseHitsAddend,omitempty"`
zhaohuabing marked this conversation as resolved.
Show resolved Hide resolved
}

// RateLimitHitsAddend specifies where the Envoy retrieves the number to reduce the rate limit counters.
//
// By default, Envoy looks up the addend from the `envoy.ratelimit.hits_addend` filter metadata.
// If there's no such metadata or the number stored in the metadata is invalid, it will use the default
// usage number of 1.
//
// This default behavior can be overridden by specifying exactly one of the fields in this RateLimitUsage.
// If either of the fields is not specified, Envoy will use the default behavior described above.
//
// See https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto.html#config-route-v3-ratelimit-hitsaddend
// for more information.
//
// +kubebuilder:validation:XValidation:rule="!(has(self.number) && has(self.format))",message="only one of number or format can be specified"
type RateLimitHitsAddend struct {
// Number specifies the fixed usage number to reduce the rate limit counters.
//
// +optional
// +notImplementedHide
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hidden until envoyproxy/ratelimit#802

Number *uint64 `json:"number,omitempty"`
// Format specifies the format of the usage number. See the Envoy documentation for the supported format which
// is the same as the access log format:
// https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format
//
// For example `%DYNAMIC_METADATA(com.test.my_filter:test_key)%"` will retrieve the usage number from the
// `com.test.my_filter` filter metadata namespace with the key `test_key`.
// Another example is `%BYTES_RECEIVED%` which will retrieve the usage number from the bytes received by the client.
//
// +optional
// +notImplementedHide
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hidden until envoyproxy/ratelimit#802

Format *string `json:"format,omitempty"`
}

// RateLimitSelectCondition specifies the attributes within the traffic flow that can
Expand Down
35 changes: 35 additions & 0 deletions api/v1alpha1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

128 changes: 128 additions & 0 deletions charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -777,6 +777,68 @@ spec:
- requests
- unit
type: object
requestHitsAddend:
description: |-
RequestHitsAddend specifies the number to reduce the rate limit counters
on the request path. If the addend is not specified, the default behavior
is to reduce the rate limit counters by 1.

When Envoy receives a request that matches the rule, it tries to reduce the
rate limit counters by the specified number. If the counter doesn't have
enough capacity, the request is rate limited.
properties:
format:
description: |-
Format specifies the format of the usage number. See the Envoy documentation for the supported format which
is the same as the access log format:
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format

For example `%DYNAMIC_METADATA(com.test.my_filter:test_key)%"` will retrieve the usage number from the
`com.test.my_filter` filter metadata namespace with the key `test_key`.
Another example is `%BYTES_RECEIVED%` which will retrieve the usage number from the bytes received by the client.
type: string
number:
description: Number specifies the fixed usage number
to reduce the rate limit counters.
format: int64
type: integer
type: object
x-kubernetes-validations:
- message: only one of number or format can be specified
rule: '!(has(self.number) && has(self.format))'
responseHitsAddend:
description: |-
ResponseHitsAddend specifies the number to reduce the rate limit counters
after the response is sent back to the client or the request stream is closed.

The addend is used to reduce the rate limit counters for the matching requests.
Since the reduction happens after the request stream is complete, the rate limit
won't be enforced for the current request, but for the subsequent matching requests.

This is optional and if not specified, the rate limit counters are not reduced
on the response path.

Currently, this is only supported for HTTP Global Rate Limits.
properties:
format:
description: |-
Format specifies the format of the usage number. See the Envoy documentation for the supported format which
is the same as the access log format:
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format

For example `%DYNAMIC_METADATA(com.test.my_filter:test_key)%"` will retrieve the usage number from the
`com.test.my_filter` filter metadata namespace with the key `test_key`.
Another example is `%BYTES_RECEIVED%` which will retrieve the usage number from the bytes received by the client.
type: string
number:
description: Number specifies the fixed usage number
to reduce the rate limit counters.
format: int64
type: integer
type: object
x-kubernetes-validations:
- message: only one of number or format can be specified
rule: '!(has(self.number) && has(self.format))'
required:
- limit
type: object
Expand Down Expand Up @@ -912,11 +974,77 @@ spec:
- requests
- unit
type: object
requestHitsAddend:
description: |-
RequestHitsAddend specifies the number to reduce the rate limit counters
on the request path. If the addend is not specified, the default behavior
is to reduce the rate limit counters by 1.

When Envoy receives a request that matches the rule, it tries to reduce the
rate limit counters by the specified number. If the counter doesn't have
enough capacity, the request is rate limited.
properties:
format:
description: |-
Format specifies the format of the usage number. See the Envoy documentation for the supported format which
is the same as the access log format:
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format

For example `%DYNAMIC_METADATA(com.test.my_filter:test_key)%"` will retrieve the usage number from the
`com.test.my_filter` filter metadata namespace with the key `test_key`.
Another example is `%BYTES_RECEIVED%` which will retrieve the usage number from the bytes received by the client.
type: string
number:
description: Number specifies the fixed usage number
to reduce the rate limit counters.
format: int64
type: integer
type: object
x-kubernetes-validations:
- message: only one of number or format can be specified
rule: '!(has(self.number) && has(self.format))'
responseHitsAddend:
description: |-
ResponseHitsAddend specifies the number to reduce the rate limit counters
after the response is sent back to the client or the request stream is closed.

The addend is used to reduce the rate limit counters for the matching requests.
Since the reduction happens after the request stream is complete, the rate limit
won't be enforced for the current request, but for the subsequent matching requests.

This is optional and if not specified, the rate limit counters are not reduced
on the response path.

Currently, this is only supported for HTTP Global Rate Limits.
properties:
format:
description: |-
Format specifies the format of the usage number. See the Envoy documentation for the supported format which
is the same as the access log format:
https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#config-access-log-format

For example `%DYNAMIC_METADATA(com.test.my_filter:test_key)%"` will retrieve the usage number from the
`com.test.my_filter` filter metadata namespace with the key `test_key`.
Another example is `%BYTES_RECEIVED%` which will retrieve the usage number from the bytes received by the client.
type: string
number:
description: Number specifies the fixed usage number
to reduce the rate limit counters.
format: int64
type: integer
type: object
x-kubernetes-validations:
- message: only one of number or format can be specified
rule: '!(has(self.number) && has(self.format))'
required:
- limit
type: object
maxItems: 16
type: array
x-kubernetes-validations:
- message: responseHitsAddend is not supported for Local Rate
Limits
rule: self.all(foo, !has(foo.responseHitsAddend))
type: object
type:
description: |-
Expand Down
26 changes: 26 additions & 0 deletions site/content/en/latest/api/extension_types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3352,6 +3352,32 @@ _Appears in:_
| `Redis` | RedisBackendType uses a redis database for the rate limit service.<br /> |


#### RateLimitHitsAddend



RateLimitHitsAddend specifies where the Envoy retrieves the number to reduce the rate limit counters.


By default, Envoy looks up the addend from the `envoy.ratelimit.hits_addend` filter metadata.
If there's no such metadata or the number stored in the metadata is invalid, it will use the default
usage number of 1.


This default behavior can be overridden by specifying exactly one of the fields in this RateLimitUsage.
If either of the fields is not specified, Envoy will use the default behavior described above.


See https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto.html#config-route-v3-ratelimit-hitsaddend
for more information.

_Appears in:_
- [RateLimitRule](#ratelimitrule)

| Field | Type | Required | Description |
| --- | --- | --- | --- |


#### RateLimitMetrics


Expand Down
26 changes: 26 additions & 0 deletions site/content/zh/latest/api/extension_types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3352,6 +3352,32 @@ _Appears in:_
| `Redis` | RedisBackendType uses a redis database for the rate limit service.<br /> |


#### RateLimitHitsAddend



RateLimitHitsAddend specifies where the Envoy retrieves the number to reduce the rate limit counters.


By default, Envoy looks up the addend from the `envoy.ratelimit.hits_addend` filter metadata.
If there's no such metadata or the number stored in the metadata is invalid, it will use the default
usage number of 1.


This default behavior can be overridden by specifying exactly one of the fields in this RateLimitUsage.
If either of the fields is not specified, Envoy will use the default behavior described above.


See https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto.html#config-route-v3-ratelimit-hitsaddend
for more information.

_Appears in:_
- [RateLimitRule](#ratelimitrule)

| Field | Type | Required | Description |
| --- | --- | --- | --- |


#### RateLimitMetrics


Expand Down
Loading
Loading