Distributed Rate Limiting¶

Traefik Enterprise supports distributed rate limiting. It's a middleware just like Traefik Proxy's rate limiting middleware, but it ensures that requests are limited over time throughout your cluster and not just on an individual proxy.

Configuration Example¶

To use distributed rate limiting, you'll need to deploy a service with the middleware enabled. Here are some examples depending on the provider you're using:

Docker

# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 50 requests is allowed.
labels:
  - "traefik.http.middlewares.test-ratelimit.plugin.ratelimit.average=100"
  - "traefik.http.middlewares.test-ratelimit.plugin.ratelimit.burst=50"

Kubernetes

# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 50 requests is allowed.
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-ratelimit
spec:
  plugin:
    rateLimit:
      average: 100
      burst: 50

File (YAML)

# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 50 requests is allowed.
http:
  middlewares:
    test-ratelimit:
      plugin:
        rateLimit:
          average: 100
          burst: 50

File (TOML)

# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 50 requests is allowed.
[http.middlewares]
  [http.middlewares.test-ratelimit.plugin.rateLimit]
    average = 100
    burst = 50

Configuration Options¶

For more information on the different configuration possibilities (average, burst, sourceCriterion etc.), refer to the Traefik Proxy Reference.

In addition, the following options are also available, specifically for Traefik Enterprise:

denyOnError¶

Optional, Default=true

The DenyOnError option forces the Traefik Proxies to return a 429 error if they cannot reach the controller to get the number of remaining requests accepted. Set to false, this option allow the request to reach the backend the case described above.

Docker

labels:
  - "traefik.http.middlewares.test-ratelimit.plugin.ratelimit.denyOnError=false"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-ratelimit
spec:
  plugin:
    rateLimit:
      denyOnError: false

File (YAML)

http:
  middlewares:
    test-ratelimit:
      plugin:
        rateLimit:
          denyOnError: false

File (TOML)

[http.middlewares]
  [http.middlewares.test-ratelimit.plugin.rateLimit]
    denyOnError = false

timeout¶

Optional, Default=200ms

Maximum amount of time allowed for the proxies reaching the controller to get the number of remaining requests accepted. If the timeout is reached, according to the option DenyOnError, the requests are rejected or allowed (with an error log).

Docker

labels:
  - "traefik.http.middlewares.test-ratelimit.plugin.ratelimit.timeout=1s"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-ratelimit
spec:
  plugin:
    rateLimit:
      timeout: 1s

File (YAML)

http:
  middlewares:
    test-ratelimit:
      plugin:
        rateLimit:
          timeout: 1s

File (TOML)

[http.middlewares]
  [http.middlewares.test-ratelimit.plugin.rateLimit]
    timeout = 1s

responseHeaders¶

Optional, Default=false

The ResponseHeaders option controls whether Traefik Enterprise injects the X-Rate-Limit-Remaining header in the response, which indicates how many tokens are left in the bucket (in the token bucket analogy) after the reservation for the request was made.

Docker

labels:
  - "traefik.http.middlewares.test-ratelimit.plugin.ratelimit.responseHeaders=true"

Kubernetes

apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
  name: test-ratelimit
spec:
  plugin:
    rateLimit:
      responseHeaders: true

File (YAML)

http:
  middlewares:
    test-ratelimit:
      plugin:
        rateLimit:
          responseHeaders: true

File (TOML)

[http.middlewares]
  [http.middlewares.test-ratelimit.plugin.rateLimit]
    responseHeaders = true

Migrating from Traefik Proxy¶

If a Traefik Proxy configuration for the rate limit middleware exists, it can adapted for Traefik Enterprise simply by using plugin.rateLimit instead of rateLimit. See the examples above for the different providers.

A Traefik Proxy middleware configuration can be kept, which will run the non-distributed version of the middleware on each proxy. This means the limiting is per-proxy and not throughout the entire cluster, so be careful.