RateLimit

    The RateLimit middleware ensures that services will receive a fair amount of requests, and allows one to define what fair is.

    Docker

    Kubernetes

    1. # Here, an average of 100 requests per second is allowed.
    2. # In addition, a burst of 50 requests is allowed.
    3. apiVersion: traefik.containo.us/v1alpha1
    4. kind: Middleware
    5. metadata:
    6.   name: test-ratelimit
    7. spec:
    8.   rateLimit:
    9.     average: 100
    10.     burst: 50

    Consul Catalog

    1. # Here, an average of 100 requests per second is allowed.
    2. # In addition, a burst of 50 requests is allowed.
    3. - "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
    4. - "traefik.http.middlewares.test-ratelimit.ratelimit.burst=50"

    Marathon

    1. "labels": {
    2.   "traefik.http.middlewares.test-ratelimit.ratelimit.average": "100",
    3.   "traefik.http.middlewares.test-ratelimit.ratelimit.burst": "50"
    4. }

    Rancher

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

    File (YAML)

    1. # Here, an average of 100 requests per second is allowed.
    2. # In addition, a burst of 50 requests is allowed.
    3. http:
    4.   middlewares:
    5.     test-ratelimit:
    6.       rateLimit:
    7.         average: 100
    8.         burst: 50

    File (TOML)

    1. # Here, an average of 100 requests per second is allowed.
    2. # In addition, a burst of 50 requests is allowed.
    3. [http.middlewares]
    4.   [http.middlewares.test-ratelimit.rateLimit]
    5.     average = 100
    6.     burst = 50

    Configuration Options

    average is the maximum rate, by default in requests per second, allowed from a given source.

    It defaults to 0, which means no rate limiting.

    The rate is actually defined by dividing average by period. So for a rate below 1 req/s, one needs to define a period larger than a second.

    Docker

    1. # 100 reqs/s
    2. labels:
    3.   - "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"

    Kubernetes

    1. # 100 reqs/s
    2. apiVersion: traefik.containo.us/v1alpha1
    3. kind: Middleware
    4. metadata:
    5.   name: test-ratelimit
    6. spec:
    7.   rateLimit:
    8.     average: 100

    Consul Catalog

    1. # 100 reqs/s
    2. - "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"

    Marathon

    1. "labels": {
    2.   "traefik.http.middlewares.test-ratelimit.ratelimit.average": "100",
    3. }

    Rancher

    1. labels:
    2.   - "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"

    File (YAML)

    1. # 100 reqs/s
    2. http:
    3.   middlewares:
    4.     test-ratelimit:
    5.       rateLimit:
    6.         average: 100

    File (TOML)

    1. # 100 reqs/s
    2. [http.middlewares]
    3.   [http.middlewares.test-ratelimit.rateLimit]
    4.     average = 100

    period, in combination with average, defines the actual maximum rate, such as:

    1. r = average / period

    It defaults to 1 second.

    Docker

    1. # 6 reqs/minute
    2. labels:
    3.   - "traefik.http.middlewares.test-ratelimit.ratelimit.average=6"
    4.   - "traefik.http.middlewares.test-ratelimit.ratelimit.period=1m"

    Kubernetes

    1. apiVersion: traefik.containo.us/v1alpha1
    2. kind: Middleware
    3. metadata:
    4.   name: test-ratelimit
    5. spec:
    6.   rateLimit:
    7.     period: 1m
    8.     average: 6

    Consul Catalog

    1. # 6 reqs/minute
    2. - "traefik.http.middlewares.test-ratelimit.ratelimit.average=6"
    3. - "traefik.http.middlewares.test-ratelimit.ratelimit.period=1m"

    Marathon

    1. "labels": {
    2.   "traefik.http.middlewares.test-ratelimit.ratelimit.average": "6",
    3.   "traefik.http.middlewares.test-ratelimit.ratelimit.period": "1m",
    4. }

    Rancher

    File (YAML)

    1. # 6 reqs/minute
    3.   middlewares:
    4.     test-ratelimit:
    5.       rateLimit:
    6.         average: 6
    7.         period: 1m
    1. # 6 reqs/minute
    2. [http.middlewares]
    3.   [http.middlewares.test-ratelimit.rateLimit]
    4.     average = 6
    5.     period = "1m"

    burst is the maximum number of requests allowed to go through in the same arbitrarily small period of time.

    It defaults to 1.

    Docker

    1. labels:
    2.   - "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"

    Kubernetes

    1. apiVersion: traefik.containo.us/v1alpha1
    2. kind: Middleware
    3. metadata:
    4.   name: test-ratelimit
    5. spec:
    6.   rateLimit:
    7.     burst: 100

    Consul Catalog

    1. - "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"

    Marathon

    1. "labels": {
    2.   "traefik.http.middlewares.test-ratelimit.ratelimit.burst": "100",
    3. }

    Rancher

    1. labels:
    2.   - "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"

    File (YAML)

    1. http:
    2.   middlewares:
    3.     test-ratelimit:
    4.       rateLimit:
    5.         burst: 100

    File (TOML)

    1. [http.middlewares]
    2.   [http.middlewares.test-ratelimit.rateLimit]
    3.     burst = 100

    The sourceCriterion option defines what criterion is used to group requests as originating from a common source. 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

    The ipStrategy option defines two parameters that configures how Traefik determines the client IP: depth, and excludedIPs.

    ipStrategy.depth

    The depth option tells Traefik to use the X-Forwarded-For header and select the IP located at the depth position (starting from the right).

    • 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).

    Docker

    1. labels:
    2.   - "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.depth=2"

    Kubernetes

    1. apiVersion: traefik.containo.us/v1alpha1
    2. kind: Middleware
    3. metadata:
    4.   name: test-ratelimit
    5. spec:
    6.   rateLimit:
    7.     sourceCriterion:
    8.       ipStrategy:
    9.         depth: 2

    Consul Catalog

    1. - "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.depth=2"

    Marathon

    1. "labels": {
    2.   "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.depth": "2"
    3. }

    Rancher

    1. labels:
    2.   - "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.depth=2"

    File (YAML)

    1. http:
    2.   middlewares:
    3.     test-ratelimit:
    4.       rateLimit:
    5.         sourceCriterion:
    6.           ipStrategy:
    7.             depth: 2

    File (TOML)

    1. [http.middlewares]
    2.   [http.middlewares.test-ratelimit.rateLimit]
    3.     [http.middlewares.test-ratelimit.rateLimit.sourceCriterion.ipStrategy]
    4.       depth = 2
    ipStrategy.excludedIPs

    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

    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

    Docker

    1. labels:
    2.   - "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"

    Kubernetes

    1. apiVersion: traefik.containo.us/v1alpha1
    2. kind: Middleware
    3. metadata:
    4.   name: test-ratelimit
    5. spec:
    6.   rateLimit:
    7.     sourceCriterion:
    8.       ipStrategy:
    9.         excludedIPs:
    10.         - 127.0.0.1/32
    11.         - 192.168.1.7

    Consul Catalog

    Marathon

    1. "labels": {
    2.   "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.excludedips": "127.0.0.1/32, 192.168.1.7"
    3. }

    Rancher

    1. labels:
    2.   - "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"

    File (YAML)

    1. http:
    2.   middlewares:
    3.     test-ratelimit:
    4.       rateLimit:
    5.         sourceCriterion:
    6.           ipStrategy:
    7.             excludedIPs:
    8.               - "127.0.0.1/32"
    9.               - "192.168.1.7"

    File (TOML)

    1. [http.middlewares]
    2.   [http.middlewares.test-ratelimit.rateLimit]
    3.     [http.middlewares.test-ratelimit.rateLimit.sourceCriterion.ipStrategy]
    4.       excludedIPs = ["127.0.0.1/32", "192.168.1.7"]

    sourceCriterion.requestHeaderName

    Name of the header used to group incoming requests.

    Docker

    1. labels:
    2.   - "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requestheadername=username"

    Kubernetes

    1. apiVersion: traefik.containo.us/v1alpha1
    2. kind: Middleware
    3. metadata:
    4.   name: test-ratelimit
    5. spec:
    6.   rateLimit:
    7.     sourceCriterion:
    8.       requestHeaderName: username

    Consul Catalog

    1. - "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requestheadername=username"

    Marathon

    1. "labels": {
    2.   "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requestheadername": "username"
    3. }

    Rancher

    1. labels:
    2.   - "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requestheadername=username"

    File (YAML)

    1. http:
    2.   middlewares:
    3.     test-ratelimit:
    4.       rateLimit:
    5.         sourceCriterion:
    6.           requestHeaderName: username

    File (TOML)

    1. [http.middlewares]
    2.   [http.middlewares.test-ratelimit.rateLimit]
    3.     [http.middlewares.test-ratelimit.rateLimit.sourceCriterion]
    4.       requestHeaderName = "username"

    sourceCriterion.requestHost

    Whether to consider the request host as the source.

    Docker

    1. labels:
    2.   - "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requesthost=true"

    Kubernetes

    1. apiVersion: traefik.containo.us/v1alpha1
    2. kind: Middleware
    3. metadata:
    4.   name: test-ratelimit
    5. spec:
    6.   rateLimit:
    7.     sourceCriterion:
    8.       requestHost: true

    Consul Catalog

    1. - "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requesthost=true"

    Marathon

    1. "labels": {
    2.   "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requesthost": "true"
    3. }

    Rancher

    1. labels:
    2.   - "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requesthost=true"

    File (YAML)

    1. http:
    2.   middlewares:
    3.     test-ratelimit:
    4.       rateLimit:
    5.         sourceCriterion:
    6.           requestHost: true

    File (TOML)

    1. [http.middlewares]
    2.   [http.middlewares.test-ratelimit.rateLimit]