.. _envoy_v3_api_file_envoy/extensions/filters/http/rate_limit_quota/v3/rate_limit_quota.proto: Rate Limit Quota (proto) ======================== .. _extension_envoy.filters.http.rate_limit_quota: This extension has the qualified name ``envoy.filters.http.rate_limit_quota`` .. note:: This extension is work-in-progress. Functionality is incomplete and it is not intended for production use. This extension has an unknown security posture and should only be used in deployments where both the downstream and upstream are trusted. .. tip:: This extension extends and can be used with the following extension category: - :ref:`envoy.filters.http ` This extension must be configured with one of the following type URLs: - :ref:`type.googleapis.com/envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig ` - :ref:`type.googleapis.com/envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaOverride ` - :ref:`type.googleapis.com/envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings ` .. warning:: This API feature is currently work-in-progress. API features marked as work-in-progress are not considered stable, are not covered by the :ref:`threat model `, are not supported by the security team, and are subject to breaking changes. Do not use this feature without understanding each of the previous points. Rate Limit Quota :ref:`configuration overview `. .. _envoy_v3_api_msg_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig: extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig ---------------------------------------------------------------------- :repo:`[extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig proto] ` Configures the Rate Limit Quota filter. Can be overridden in the per-route and per-host configurations. The more specific definition completely overrides the less specific definition. .. code-block:: json :force: { "rlqs_server": {...}, "domain": ..., "bucket_matchers": {...}, "filter_enabled": {...}, "filter_enforced": {...}, "request_headers_to_add_when_not_enforced": [] } .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig.rlqs_server: rlqs_server (:ref:`config.core.v3.GrpcService `, *REQUIRED*) Configures the gRPC Rate Limit Quota Service (RLQS) RateLimitQuotaService. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig.domain: domain (`string `_, *REQUIRED*) The application domain to use when calling the service. This enables sharing the quota server between different applications without fear of overlap. E.g., "envoy". .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig.bucket_matchers: bucket_matchers (:ref:`.xds.type.matcher.v3.Matcher `, *REQUIRED*) The match tree to use for grouping incoming requests into buckets. Example: .. validated-code-block:: yaml :type-name: xds.type.matcher.v3.Matcher matcher_list: matchers: # Assign requests with header['env'] set to 'staging' to the bucket { name: 'staging' } - predicate: single_predicate: input: typed_config: '@type': type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput header_name: env value_match: exact: staging on_match: action: typed_config: '@type': type.googleapis.com/envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings bucket_id_builder: bucket_id_builder: name: string_value: staging # Assign requests with header['user_group'] set to 'admin' to the bucket { acl: 'admin_users' } - predicate: single_predicate: input: typed_config: '@type': type.googleapis.com/xds.type.matcher.v3.HttpAttributesCelMatchInput custom_match: typed_config: '@type': type.googleapis.com/xds.type.matcher.v3.CelMatcher expr_match: # Shortened for illustration purposes. Here should be parsed CEL expression: # request.headers['user_group'] == 'admin' parsed_expr: {} on_match: action: typed_config: '@type': type.googleapis.com/envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings bucket_id_builder: bucket_id_builder: acl: string_value: admin_users # Catch-all clause for the requests not matched by any of the matchers. # In this example, deny all requests. on_no_match: action: typed_config: '@type': type.googleapis.com/envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings no_assignment_behavior: fallback_rate_limit: blanket_rule: DENY_ALL .. attention:: The first matched group wins. Once the request is matched into a bucket, matcher evaluation ends. Use ``on_no_match`` field to assign the catch-all bucket. If a request is not matched into any bucket, and there's no ``on_no_match`` field configured, the request will be ALLOWED by default. It will NOT be reported to the RLQS server. Refer to :ref:`Unified Matcher API ` documentation for more information on the matcher trees. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig.filter_enabled: filter_enabled (:ref:`config.core.v3.RuntimeFractionalPercent `) If set, this will enable -- but not necessarily enforce -- the rate limit for the given fraction of requests. Defaults to 100% of requests. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig.filter_enforced: filter_enforced (:ref:`config.core.v3.RuntimeFractionalPercent `) If set, this will enforce the rate limit decisions for the given fraction of requests. For requests that are not enforced the filter will still obtain the quota and include it in the load computation, however the request will always be allowed regardless of the outcome of quota application. This allows validation or testing of the rate limiting service infrastructure without disrupting existing traffic. Note: this only applies to the fraction of enabled requests. Defaults to 100% of requests. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaFilterConfig.request_headers_to_add_when_not_enforced: request_headers_to_add_when_not_enforced (**repeated** :ref:`config.core.v3.HeaderValueOption `) Specifies a list of HTTP headers that should be added to each request that has been rate limited and is also forwarded upstream. This can only occur when the filter is enabled but not enforced. .. _envoy_v3_api_msg_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaOverride: extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaOverride ------------------------------------------------------------------ :repo:`[extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaOverride proto] ` Per-route and per-host configuration overrides. The more specific definition completely overrides the less specific definition. .. code-block:: json :force: { "domain": ..., "bucket_matchers": {...} } .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaOverride.domain: domain (`string `_) The application domain to use when calling the service. This enables sharing the quota server between different applications without fear of overlap. E.g., "envoy". If empty, inherits the value from the less specific definition. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaOverride.bucket_matchers: bucket_matchers (:ref:`.xds.type.matcher.v3.Matcher `) The match tree to use for grouping incoming requests into buckets. If set, fully overrides the bucket matchers provided on the less specific definition. If not set, inherits the value from the less specific definition. See usage example: :ref:`RateLimitQuotaFilterConfig.bucket_matchers `. .. _envoy_v3_api_msg_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings: extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings ------------------------------------------------------------------------ :repo:`[extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings proto] ` Rate Limit Quota Bucket Settings to apply on the successful ``bucket_matchers`` match. Specify this message in the :ref:`Matcher.OnMatch.action ` field of the ``bucket_matchers`` matcher tree to assign the matched requests to the Quota Bucket. Usage example: :ref:`RateLimitQuotaFilterConfig.bucket_matchers `. .. code-block:: json :force: { "bucket_id_builder": {...}, "reporting_interval": {...}, "deny_response_settings": {...}, "no_assignment_behavior": {...}, "expired_assignment_behavior": {...} } .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.bucket_id_builder: bucket_id_builder (:ref:`extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder `) ``BucketId`` builder. :ref:`BucketId ` is a map from the string key to the string value which serves as bucket identifier common for on the control plane and the data plane. While ``BucketId`` is always static, ``BucketIdBuilder`` allows to populate map values with the dynamic properties associated with the each individual request. Example 1: static fields only ``BucketIdBuilder``: .. validated-code-block:: yaml :type-name: envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder bucket_id_builder: name: string_value: my_bucket hello: string_value: world Produces the following ``BucketId`` for all requests: .. validated-code-block:: yaml :type-name: envoy.service.rate_limit_quota.v3.BucketId bucket: name: my_bucket hello: world Example 2: static and dynamic fields .. validated-code-block:: yaml :type-name: envoy.extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder bucket_id_builder: name: string_value: my_bucket env: custom_value: typed_config: '@type': type.googleapis.com/envoy.type.matcher.v3.HttpRequestHeaderMatchInput header_name: environment In this example, the value of ``BucketId`` key ``env`` is substituted from the ``environment`` request header. This is equivalent to the following ``pseudo-code``: .. code-block:: yaml name: 'my_bucket' env: $header['environment'] For example, the request with the HTTP header ``env`` set to ``staging`` will produce the following ``BucketId``: .. validated-code-block:: yaml :type-name: envoy.service.rate_limit_quota.v3.BucketId bucket: name: my_bucket env: staging For the request with the HTTP header ``environment`` set to ``prod``, will produce: .. validated-code-block:: yaml :type-name: envoy.service.rate_limit_quota.v3.BucketId bucket: name: my_bucket env: prod .. note:: The order of ``BucketId`` keys do not matter. Buckets ``{ a: 'A', b: 'B' }`` and ``{ b: 'B', a: 'A' }`` are identical. If not set, requests will NOT be reported to the server, and will always limited according to :ref:`no_assignment_behavior ` configuration. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.reporting_interval: reporting_interval (`Duration `_, *REQUIRED*) The interval at which the data plane (RLQS client) is to report quota usage for this bucket. When the first request is matched to a bucket with no assignment, the data plane is to report the request immediately in the :ref:`RateLimitQuotaUsageReports ` message. For the RLQS server, this signals that the data plane is now subscribed to the quota assignments in this bucket, and will start sending the assignment as described in the :ref:`RLQS documentation `. After sending the initial report, the data plane is to continue reporting the bucket usage with the internal specified in this field. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.deny_response_settings: deny_response_settings (:ref:`extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.DenyResponseSettings `) Customize the deny response to the requests over the rate limit. If not set, the filter will be configured as if an empty message is set, and will behave according to the defaults specified in :ref:`DenyResponseSettings `. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.no_assignment_behavior: no_assignment_behavior (:ref:`extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.NoAssignmentBehavior `) Configures the behavior in the "no assignment" state: after the first request has been matched to the bucket, and before the the RLQS server returns the first quota assignment. If not set, the default behavior is to allow all requests. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.expired_assignment_behavior: expired_assignment_behavior (:ref:`extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior `) Configures the behavior in the "expired assignment" state: the bucket's assignment has expired, and cannot be refreshed. If not set, the bucket is abandoned when its ``active`` assignment expires. The process of abandoning the bucket, and restarting the subscription is described in the :ref:`AbandonAction ` message. .. _envoy_v3_api_msg_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.NoAssignmentBehavior: extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.NoAssignmentBehavior --------------------------------------------------------------------------------------------- :repo:`[extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.NoAssignmentBehavior proto] ` Configures the behavior after the first request has been matched to the bucket, and before the the RLQS server returns the first quota assignment. .. code-block:: json :force: { "fallback_rate_limit": {...} } .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.NoAssignmentBehavior.fallback_rate_limit: fallback_rate_limit (:ref:`type.v3.RateLimitStrategy `, *REQUIRED*) Apply pre-configured rate limiting strategy until the server sends the first assignment. .. _envoy_v3_api_msg_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior: extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior -------------------------------------------------------------------------------------------------- :repo:`[extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior proto] ` Specifies the behavior when the bucket's assignment has expired, and cannot be refreshed for any reason. .. code-block:: json :force: { "expired_assignment_behavior_timeout": {...}, "fallback_rate_limit": {...}, "reuse_last_assignment": {...} } .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior.expired_assignment_behavior_timeout: expired_assignment_behavior_timeout (`Duration `_) Limit the time :ref:`ExpiredAssignmentBehavior ` is applied. If the server doesn't respond within this duration: 1. Selected ``ExpiredAssignmentBehavior`` is no longer applied. 2. The bucket is abandoned. The process of abandoning the bucket is described in the :ref:`AbandonAction ` message. 3. If a new request is matched into the bucket that has become abandoned, the data plane restarts the subscription to the bucket. The process of restarting the subscription is described in the :ref:`AbandonAction ` message. If the field is not set, the ``ExpiredAssignmentBehavior`` time is **not limited**: it applies to the bucket until replaced by an ``active`` assignment. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior.fallback_rate_limit: fallback_rate_limit (:ref:`type.v3.RateLimitStrategy `) Apply the rate limiting strategy to all requests matched into the bucket until the RLQS server sends a new assignment, or the :ref:`expired_assignment_behavior_timeout ` runs out. Precisely one of :ref:`fallback_rate_limit `, :ref:`reuse_last_assignment ` must be set. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior.reuse_last_assignment: reuse_last_assignment (:ref:`extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior.ReuseLastAssignment `) Reuse the last ``active`` assignment until the RLQS server sends a new assignment, or the :ref:`expired_assignment_behavior_timeout ` runs out. Precisely one of :ref:`fallback_rate_limit `, :ref:`reuse_last_assignment ` must be set. .. _envoy_v3_api_msg_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior.ReuseLastAssignment: extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior.ReuseLastAssignment ---------------------------------------------------------------------------------------------------------------------- :repo:`[extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.ExpiredAssignmentBehavior.ReuseLastAssignment proto] ` Reuse the last known quota assignment, effectively extending it for the duration specified in the :ref:`expired_assignment_behavior_timeout ` field. .. _envoy_v3_api_msg_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.DenyResponseSettings: extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.DenyResponseSettings --------------------------------------------------------------------------------------------- :repo:`[extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.DenyResponseSettings proto] ` Customize the deny response to the requests over the rate limit. .. code-block:: json :force: { "http_status": {...}, "http_body": {...}, "grpc_status": {...}, "response_headers_to_add": [] } .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.DenyResponseSettings.http_status: http_status (:ref:`type.v3.HttpStatus `) HTTP response code to deny for HTTP requests (gRPC excluded). Defaults to 429 (:ref:`StatusCode.TooManyRequests`). .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.DenyResponseSettings.http_body: http_body (`BytesValue `_) HTTP response body used to deny for HTTP requests (gRPC excluded). If not set, an empty body is returned. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.DenyResponseSettings.grpc_status: grpc_status (`Status `_) Configure the deny response for gRPC requests over the rate limit. Allows to specify the `RPC status code `_, and the error message. Defaults to the Status with the RPC Code ``UNAVAILABLE`` and empty message. To identify gRPC requests, Envoy checks that the ``Content-Type`` header is ``application/grpc``, or one of the various ``application/grpc+`` values. .. note:: The HTTP code for a gRPC response is always 200. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.DenyResponseSettings.response_headers_to_add: response_headers_to_add (**repeated** :ref:`config.core.v3.HeaderValueOption `) Specifies a list of HTTP headers that should be added to each response for requests that have been rate limited. Applies both to plain HTTP, and gRPC requests. The headers are added even when the rate limit quota was not enforced. .. _envoy_v3_api_msg_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder: extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder ---------------------------------------------------------------------------------------- :repo:`[extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder proto] ` ``BucketIdBuilder`` makes it possible to build :ref:`BucketId ` with values substituted from the dynamic properties associated with each individual request. See usage examples in the docs to :ref:`bucket_id_builder ` field. .. code-block:: json :force: { "bucket_id_builder": {...} } .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder.bucket_id_builder: bucket_id_builder (**repeated** map<`string `_, :ref:`extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder.ValueBuilder `>) The map translated into the ``BucketId`` map. The ``string key`` of this map and becomes the key of ``BucketId`` map as is. The ``ValueBuilder value`` for the key can be: * static ``StringValue string_value`` — becomes the value in the ``BucketId`` map as is. * dynamic ``TypedExtensionConfig custom_value`` — evaluated for each request. Must produce a string output, which becomes the value in the the ``BucketId`` map. See usage examples in the docs to :ref:`bucket_id_builder ` field. .. _envoy_v3_api_msg_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder.ValueBuilder: extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder.ValueBuilder ----------------------------------------------------------------------------------------------------- :repo:`[extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder.ValueBuilder proto] ` Produces the value of the :ref:`BucketId ` map. .. code-block:: json :force: { "string_value": ..., "custom_value": {...} } .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder.ValueBuilder.string_value: string_value (`string `_) Static string value — becomes the value in the :ref:`BucketId ` map as is. Precisely one of :ref:`string_value `, :ref:`custom_value ` must be set. .. _envoy_v3_api_field_extensions.filters.http.rate_limit_quota.v3.RateLimitQuotaBucketSettings.BucketIdBuilder.ValueBuilder.custom_value: custom_value (:ref:`config.core.v3.TypedExtensionConfig `) Dynamic value — evaluated for each request. Must produce a string output, which becomes the value in the :ref:`BucketId ` map. For example, extensions with the ``envoy.matching.http.input`` category can be used. Precisely one of :ref:`string_value `, :ref:`custom_value ` must be set.