Common rate limit components

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

api/v2/ratelimit/ratelimit.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”.

  1. ["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.

  1. ["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).

  1. ["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.

  1. ["authenticated": "true"], ["client_id": "foo"]

What it does: Limits all traffic for an authenticated client “foo”

  1. ["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.

  1. {
  2.   "entries": [],
  3.   "limit": "{...}"
  4. }

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.

extensions.common.ratelimit.v3.RateLimitDescriptor.Entry

[extensions.common.ratelimit.v3.RateLimitDescriptor.Entry proto]

  1. {
  2.   "key": "...",
  3.   "value": "..."
  4. }

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.

  1. {
  2.   "requests_per_unit": "...",
  3.   "unit": "..."
  4. }

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]

  1. {
  2.   "entries": [],
  3.   "token_bucket": "{...}"
  4. }

entries

(repeated extensions.common.ratelimit.v3.RateLimitDescriptor.Entry, REQUIRED) Descriptor entries.

token_bucket

(type.v3.TokenBucket, REQUIRED) Token Bucket algorithm for local ratelimiting.

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.