Local Rate limit (proto)

This extension has the qualified name envoy.filters.http.local_ratelimit

Note

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:

This extension must be configured with one of the following type URLs:

Local Rate limit configuration overview.

extensions.filters.http.local_ratelimit.v3.LocalRateLimit

[extensions.filters.http.local_ratelimit.v3.LocalRateLimit proto]

{
  "stat_prefix": ...,
  "status": {...},
  "token_bucket": {...},
  "filter_enabled": {...},
  "filter_enforced": {...},
  "request_headers_to_add_when_not_enforced": [],
  "response_headers_to_add": [],
  "descriptors": [],
  "stage": ...,
  "local_rate_limit_per_downstream_connection": ...,
  "enable_x_ratelimit_headers": ...,
  "vh_rate_limits": ...
}
stat_prefix

(string, REQUIRED) The human readable prefix to use when emitting stats.

status

(type.v3.HttpStatus) This field allows for a custom HTTP response status code to the downstream client when the request has been rate limited. Defaults to 429 (TooManyRequests).

Note

If this is set to < 400, 429 will be used instead.

token_bucket

(type.v3.TokenBucket) The token bucket configuration to use for rate limiting requests that are processed by this filter. Each request processed by the filter consumes a single token. If the token is available, the request will be allowed. If no tokens are available, the request will receive the configured rate limit status.

Note

It’s fine for the token bucket to be unset for the global configuration since the rate limit can be applied at a the virtual host or route level. Thus, the token bucket must be set for the per route configuration otherwise the config will be rejected.

Note

When using per route configuration, the bucket becomes unique to that route.

Note

In the current implementation the token bucket’s fill_interval must be >= 50ms to avoid too aggressive refills.

filter_enabled

(config.core.v3.RuntimeFractionalPercent) If set, this will enable – but not necessarily enforce – the rate limit for the given fraction of requests. Defaults to 0% of requests for safety.

filter_enforced

(config.core.v3.RuntimeFractionalPercent) If set, this will enforce the rate limit decisions for the given fraction of requests.

Note: this only applies to the fraction of enabled requests.

Defaults to 0% of requests for safety.

request_headers_to_add_when_not_enforced

(repeated 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.

response_headers_to_add

(repeated config.core.v3.HeaderValueOption) Specifies a list of HTTP headers that should be added to each response for requests that have been rate limited. This occurs when the filter is either enabled or fully enforced.

descriptors

(repeated extensions.common.ratelimit.v3.LocalRateLimitDescriptor) The rate limit descriptor list to use in the local rate limit to override on. The rate limit descriptor is selected by the first full match from the request descriptors.

Example on how to use this.

Note

In the current implementation the descriptor’s token bucket fill_interval must be a multiple global token bucket’s fill interval.

The descriptors must match verbatim for rate limiting to apply. There is no partial match by a subset of descriptor entries in the current implementation.

stage

(uint32) Specifies the rate limit configurations to be applied with the same stage number. If not set, the default stage number is 0.

Note

The filter supports a range of 0 - 10 inclusively for stage numbers.

local_rate_limit_per_downstream_connection

(bool) Specifies the scope of the rate limiter’s token bucket. If set to false, the token bucket is shared across all worker threads, thus the rate limits are applied per Envoy process. If set to true, a token bucket is allocated for each connection. Thus the rate limits are applied per connection thereby allowing one to rate limit requests on a per connection basis. If unspecified, the default value is false.

enable_x_ratelimit_headers

(extensions.common.ratelimit.v3.XRateLimitHeadersRFCVersion) Defines the standard version to use for X-RateLimit headers emitted by the filter.

Disabled by default.

vh_rate_limits

(extensions.common.ratelimit.v3.VhRateLimitsOptions) Specifies if the local rate limit filter should include the virtual host rate limits.