Common rate limit components (proto)
extensions.common.ratelimit.v3.RateLimitDescriptor
[extensions.common.ratelimit.v3.RateLimitDescriptor proto]
A RateLimitDescriptor is a list of hierarchical entries that are used by the service to determine the final rate limit key and overall allowed limit. Here are some examples of how they might be used for the domain “envoy”.
["authenticated": "false"], ["remote_address": "10.0.0.1"]
What it does: Limits all unauthenticated traffic for the IP address 10.0.0.1. The configuration supplies a default limit for the remote_address key. If there is a desire to raise the limit for 10.0.0.1 or block it entirely it can be specified directly in the configuration.
["authenticated": "false"], ["path": "/foo/bar"]
What it does: Limits all unauthenticated traffic globally for a specific path (or prefix if configured that way in the service).
["authenticated": "false"], ["path": "/foo/bar"], ["remote_address": "10.0.0.1"]
What it does: Limits unauthenticated traffic to a specific path for a specific IP address. Like (1) we can raise/block specific IP addresses if we want with an override configuration.
["authenticated": "true"], ["client_id": "foo"]
What it does: Limits all traffic for an authenticated client “foo”
["authenticated": "true"], ["client_id": "foo"], ["path": "/foo/bar"]
What it does: Limits traffic to a specific path for an authenticated client “foo”
The idea behind the API is that (1)/(2)/(3) and (4)/(5) can be sent in 1 request if desired. This enables building complex application scenarios with a generic backend.
Optionally the descriptor can contain a limit override under a “limit” key, that specifies the number of requests per unit to use instead of the number configured in the rate limiting service.
{
"entries": [],
"limit": {...},
"hits_addend": {...}
}
- entries
(repeated extensions.common.ratelimit.v3.RateLimitDescriptor.Entry, REQUIRED) Descriptor entries.
- limit
(extensions.common.ratelimit.v3.RateLimitDescriptor.RateLimitOverride) Optional rate limit override to supply to the ratelimit service.
- hits_addend
(UInt64Value) Optional hits_addend for the rate limit descriptor. If set the value will override the request level hits_addend.
extensions.common.ratelimit.v3.RateLimitDescriptor.Entry
[extensions.common.ratelimit.v3.RateLimitDescriptor.Entry proto]
{
"key": ...,
"value": ...
}
- key
(string, REQUIRED) Descriptor key.
- value
(string, REQUIRED) Descriptor value.
extensions.common.ratelimit.v3.RateLimitDescriptor.RateLimitOverride
[extensions.common.ratelimit.v3.RateLimitDescriptor.RateLimitOverride proto]
Override rate limit to apply to this descriptor instead of the limit configured in the rate limit service. See rate limit override for more information.
{
"requests_per_unit": ...,
"unit": ...
}
- requests_per_unit
(uint32) The number of requests per unit of time.
- unit
(type.v3.RateLimitUnit) The unit of time.
extensions.common.ratelimit.v3.LocalRateLimitDescriptor
[extensions.common.ratelimit.v3.LocalRateLimitDescriptor proto]
Configuration used to enable local rate limiting.
Note
The LocalRateLimitDescriptor is used to configure a local rate limit rule with a token
bucket algorithm. The RateLimitDescriptor is used to represent a list of symbols that
are used to match against the rate limit rule.
{
"entries": [],
"token_bucket": {...}
}
- entries
(repeated extensions.common.ratelimit.v3.RateLimitDescriptor.Entry, REQUIRED) Descriptor entries.
- token_bucket
(type.v3.TokenBucket, REQUIRED) Token Bucket algorithm for local ratelimiting.
extensions.common.ratelimit.v3.LocalClusterRateLimit
[extensions.common.ratelimit.v3.LocalClusterRateLimit proto]
Configuration used to enable local cluster level rate limiting where the token buckets will be shared across all the Envoy instances in the local cluster. A share will be calculated based on the membership of the local cluster dynamically and the configuration. When the limiter refilling the token bucket, the share will be applied. By default, the token bucket will be shared evenly.
See local cluster name for more context about local cluster.
Enum extensions.common.ratelimit.v3.XRateLimitHeadersRFCVersion
[extensions.common.ratelimit.v3.XRateLimitHeadersRFCVersion proto]
Defines the version of the standard to use for X-RateLimit headers.
- OFF
(DEFAULT) X-RateLimit headers disabled.
- DRAFT_VERSION_03
Use draft RFC Version 03 where 3 headers will be added:
X-RateLimit-Limit- indicates the request-quota associated to the client in the current time-window followed by the description of the quota policy. The value is returned by the maximum tokens of the token bucket.X-RateLimit-Remaining- indicates the remaining requests in the current time-window. The value is returned by the remaining tokens in the token bucket.X-RateLimit-Reset- indicates the number of seconds until reset of the current time-window. The value is returned by the remaining fill interval of the token bucket.
Enum extensions.common.ratelimit.v3.VhRateLimitsOptions
[extensions.common.ratelimit.v3.VhRateLimitsOptions proto]
- OVERRIDE
(DEFAULT) Use the virtual host rate limits unless the route has a rate limit policy.
- INCLUDE
Use the virtual host rate limits even if the route has a rate limit policy.
- IGNORE
Ignore the virtual host rate limits even if the route does not have a rate limit policy.