Distributed RateLimit

The Distributed RateLimit middleware ensures that requests are limited over time throughout your cluster and not only on an individual proxy.

It is based on a token bucket implementation. In this analogy, the limit parameter (defined below) is the rate at which the bucket refills, and the burst is the size (volume) of the bucket.

---

Configuration Options

limit

Field	Description	Default	Required
limit	Defines the number of requests allowed during the period from a given source.	0	No

It defaults to 0, which means no rate limiting.

The rate is defined by the combination of limit and period. For a rate below 1 req/s, one needs to define a period larger than a second.

Rate limit of 100req/s

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-distributedratelimit
spec:
  plugin:
    distributedRateLimit:
      limit: 100

period

Field	Description	Default	Required
period	Defines in combination with limit, the actual maximum rate, such as: r = limit / period	1s	No

Rate limit of 100req per minute

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-distributedratelimit
spec:
  plugin:
    distributedRateLimit:
      limit: 100
      period: 1m

burst

Field	Description	Default	Required
burst	Defines the maximum number of requests allowed to go through in the same arbitrarily small period of time.	1	No

It defaults to 1.

Burst to 100 requests

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-distributedratelimit
spec:
  plugin:
    distributedRateLimit:
      burst: 100

sourceCriterion

Field	Description	Default	Required
sourceCriterion	Defines what criterion is used to group requests as originating from a common source.		No

If several strategies are defined at the same time, an error will be raised. If none are set, the default is to use the request's remote address field (as an ipStrategy).

sourceCriterion.ipStrategy

Field	Description	Default	Required
sourceCriterion.ipStrategy	Defines two parameters that configures how Traefik determines the client IP: depth, and excludedIPs.	false	No

info

As a middleware, rate-limiting happens before the actual proxying to the backend takes place. In addition, the previous network hop only gets appended to X-Forwarded-For during the last stages of proxying, for example, after it has already passed through rate-limiting. Therefore, during rate-limiting, as the previous network hop is not yet present in X-Forwarded-For, it cannot be found and/or relied upon.

ipStrategy.depth

Field	Description	Default	Required
ipStrategy.depth	Tells Traefik to use the X-Forwarded-For header and select the IP located at the depth position (starting from the right).	0	No

• If depth is greater than the total number of IPs in X-Forwarded-For, then the client IP is empty.
• depth is ignored if its value is less than or equal to 0.

Example of Depth & X-Forwarded-For

If depth is set to 2, and the request X-Forwarded-For header is "10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1" then the "real" client IP is "10.0.0.1" (at depth 4) but the IP used as the criterion is "12.0.0.1" (depth=2).

X-Forwarded-For	depth	clientIP
"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"	1	"13.0.0.1"
"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"	3	"11.0.0.1"
"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"	5	""

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-distributedratelimit
spec:
  plugin:
    distributedRateLimit:
      sourceCriterion:
        ipStrategy:
          depth: 2

ipStrategy.excludedIPs

info

Contrary to what the name might suggest, this option is not about excluding an IP from the rate limiter, and therefore cannot be used to deactivate rate limiting for some IPs. If depth is specified, excludedIPs is ignored.

excludedIPs is meant to address two classes of somewhat distinct use-cases:

1. Distinguish IPs which are behind the same (set of) reverse-proxies so that each of them contributes, independently to the others, to its own rate-limit "bucket" (cf the leaky bucket analogy). In this case, excludedIPs should be set to match the list of X-Forwarded-For IPs that are to be excluded, in order to find the actual clientIP.

Each IP as a distinct source

X-Forwarded-For	excludedIPs	clientIP
"10.0.0.1,11.0.0.1,12.0.0.1"	"11.0.0.1,12.0.0.1"	"10.0.0.1"
"10.0.0.2,11.0.0.1,12.0.0.1"	"11.0.0.1,12.0.0.1"	"10.0.0.2"

2. Group together a set of IPs (also behind a common set of reverse-proxies) so that they are considered the same source, and all contribute to the same rate-limit bucket.

Group IPs together as same source

X-Forwarded-For	excludedIPs	clientIP
"10.0.0.1,11.0.0.1,12.0.0.1"	"12.0.0.1"	"11.0.0.1"
"10.0.0.2,11.0.0.1,12.0.0.1"	"12.0.0.1"	"11.0.0.1"
"10.0.0.3,11.0.0.1,12.0.0.1"	"12.0.0.1"	"11.0.0.1"

For completeness, below are additional examples to illustrate how the matching works. For a given request the list of X-Forwarded-For IPs is checked from most recent to most distant against the excludedIPs pool, and the first IP that is not in the pool (if any) is returned.

Matching for clientIP

X-Forwarded-For	excludedIPs	clientIP
"10.0.0.1,11.0.0.1,13.0.0.1"	"11.0.0.1"	"13.0.0.1"
"10.0.0.1,11.0.0.1,13.0.0.1"	"15.0.0.1,16.0.0.1"	"13.0.0.1"
"10.0.0.1,11.0.0.1"	"10.0.0.1,11.0.0.1"	""

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-distributedratelimit
spec:
  plugin:
    distributedRateLimit:
      sourceCriterion:
        ipStrategy:
          excludedIPs:
          - 127.0.0.1/32
          - 192.168.1.7

sourceCriterion.requestHeaderName

Field	Description	Default	Required
sourceCriterion.requestHeaderName	Defines the name of the header used to group incoming requests.	""	No

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-distributedratelimit
spec:
  plugin:
    distributedRateLimit:
      sourceCriterion:
        requestHeaderName: username

sourceCriterion.requestHost

Field	Description	Default	Required
sourceCriterion.requestHost	Whether to consider the request host as the source.	true	No

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-distributedratelimit
spec:
  plugin:
    distributedRateLimit:
      sourceCriterion:
        requestHost: true

denyOnError

Field	Description	Default	Required
denyOnError	Forces Traefik Hub to return a 429 error if they cannot get the number of remaining requests accepted. Set to false, this option allows the request to reach the backend.	true	No

denyOnError sets to false

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-distributedratelimit
spec:
  plugin:
    distributedRateLimit:
      denyOnError: false

responseHeaders

Field	Description	Default	Required
responseHeaders	Controls whether Traefik Hub injects the rate limiting headers in the response.	false	No

This adds these headers to the response:

• X-Rate-Limit-Remaining
• X-RateLimit-Limit
• X-RateLimit-Period
• X-RateLimit-Reset

The added headers indicate how many tokens are left in the bucket (in the token bucket analogy) after the reservation for the request was made.

responseHeaders sets to true

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-distributedratelimit
spec:
  plugin:
    distributedRateLimit:
      responseHeaders: true

store.redis

Connection parameters to your Redis server are attached to your Middleware deployment.

The following Redis modes are supported:

• Single instance mode
• Redis Cluster
• Redis Sentinel

info

For more information about Redis, we recommend the official Redis documentation.

The table below lists the configuration options in Traefik Hub to connect to Redis and store middleware information.

Value	Description	Required
redis.endpoints	Endpoints of the Redis instances to connect to (example: redis.traefik-hub.svc.cluster.local:6379)	Yes
redis.username	The username Traefik Hub will use to connect to Redis	No
redis.password	The password Traefik Hub will use to connect to Redis	No
redis.database	The database Traefik Hub will use to sore information (default: 0)	No
redis.cluster	Enable Redis Cluster	No
redis.tls.caBundle	Custom CA bundle	No
redis.tls.cert	TLS certificate	No
redis.tls.key	TLS key	No
redis.tls.insecureSkipVerify	Allow skipping the TLS verification	No
redis.sentinel.masterSet	Name of the set of main nodes to use for main selection. Required when using Sentinel.	No
redis.sentinel.username	Username to use for sentinel authentication (can be different from username)	No
redis.sentinel.password	Password to use for sentinel authentication (can be different from password)	No

info

If you use Redis in single instance mode or Redis Sentinel, you can configure the database field. This value won't be taken into account if you use Redis Cluster (only database 0 is available).

In this case, a warning is displayed, and the value is ignored.

Example

Allowing burst

# Here, a  limit of 100 requests per second is allowed.
# In addition, a burst of 200 requests is allowed.
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
    name: test-distributedratelimit
spec:
  plugin:
    distributedRateLimit:
      burst: 200
      denyOnError: false
      limit: 100
      period: 1s
      responseHeaders: true
      sourceCriterion:
        ipStrategy:
          excludedIPs:
            - 172.20.176.201
      store:
        redis:
          endpoints:
            - my-release-redis-master.default.svc.cluster.local:6379
          password: urn:k8s:secret:redis:password
          timeout: 500ms