From efc5b8790add581d4e68ef3cbb49a12124d1e82c Mon Sep 17 00:00:00 2001 From: Takeshi Yoneda Date: Mon, 23 Dec 2024 13:28:40 +0900 Subject: [PATCH] more on the doc Signed-off-by: Takeshi Yoneda --- api/v1alpha1/ratelimit_types.go | 15 ++++++-- ....envoyproxy.io_backendtrafficpolicies.yaml | 36 ++++++++++++++----- site/content/en/latest/api/extension_types.md | 7 +++- site/content/zh/latest/api/extension_types.md | 7 +++- 4 files changed, 52 insertions(+), 13 deletions(-) diff --git a/api/v1alpha1/ratelimit_types.go b/api/v1alpha1/ratelimit_types.go index dfdcfa953f1d..54d659368d68 100644 --- a/api/v1alpha1/ratelimit_types.go +++ b/api/v1alpha1/ratelimit_types.go @@ -124,7 +124,11 @@ type RateLimitRule struct { // 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 one of the fields in this RateLimitUsage. +// 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 { @@ -133,8 +137,13 @@ type RateLimitHitsAddend struct { // +optional // +notImplementedHide Number *uint64 `json:"number,omitempty"` - // Format specifies the format of the usage number. See the Envoy documentation for the supported formats: - // https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto.html#config-route-v3-ratelimit-hitsaddend + // 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 diff --git a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml index be8a7a9566ee..757623ef6160 100644 --- a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml +++ b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backendtrafficpolicies.yaml @@ -789,8 +789,13 @@ spec: properties: format: description: |- - Format specifies the format of the usage number. See the Envoy documentation for the supported formats: - https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto.html#config-route-v3-ratelimit-hitsaddend + 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 @@ -817,8 +822,13 @@ spec: properties: format: description: |- - Format specifies the format of the usage number. See the Envoy documentation for the supported formats: - https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto.html#config-route-v3-ratelimit-hitsaddend + 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 @@ -976,8 +986,13 @@ spec: properties: format: description: |- - Format specifies the format of the usage number. See the Envoy documentation for the supported formats: - https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto.html#config-route-v3-ratelimit-hitsaddend + 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 @@ -1004,8 +1019,13 @@ spec: properties: format: description: |- - Format specifies the format of the usage number. See the Envoy documentation for the supported formats: - https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/route/v3/route_components.proto.html#config-route-v3-ratelimit-hitsaddend + 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 diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md index bf704f70ce2d..33ca0a3ffbb6 100644 --- a/site/content/en/latest/api/extension_types.md +++ b/site/content/en/latest/api/extension_types.md @@ -3364,7 +3364,12 @@ If there's no such metadata or the number stored in the metadata is invalid, it usage number of 1. -This default behavior can be overridden by specifying one of the fields in this RateLimitUsage. +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) diff --git a/site/content/zh/latest/api/extension_types.md b/site/content/zh/latest/api/extension_types.md index bf704f70ce2d..33ca0a3ffbb6 100644 --- a/site/content/zh/latest/api/extension_types.md +++ b/site/content/zh/latest/api/extension_types.md @@ -3364,7 +3364,12 @@ If there's no such metadata or the number stored in the metadata is invalid, it usage number of 1. -This default behavior can be overridden by specifying one of the fields in this RateLimitUsage. +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)