traefik/docs/content/middlewares/http/ratelimit.md

title	description
Traefik RateLimit Documentation	Traefik Proxy's HTTP RateLimit middleware ensures Services receive fair amounts of requests. Read the technical documentation.

RateLimit

To Control the Number of Requests Going to a Service {: .subtitle }

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

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

Configuration Example

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

# Here, an average 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-ratelimit
spec:
  rateLimit:
    average: 100
    burst: 200

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

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

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

Configuration Options

average

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.

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

# 100 reqs/s
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-ratelimit
spec:
  rateLimit:
    average: 100

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

# 100 reqs/s
http:
  middlewares:
    test-ratelimit:
      rateLimit:
        average: 100

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

period

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

r = average / period

It defaults to 1 second.

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

# 6 reqs/minute
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-ratelimit
spec:
  rateLimit:
    period: 1m
    average: 6

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

# 6 reqs/minute
http:
  middlewares:
    test-ratelimit:
      rateLimit:
        average: 6
        period: 1m

# 6 reqs/minute
[http.middlewares]
  [http.middlewares.test-ratelimit.rateLimit]
    average = 6
    period = "1m"

burst

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

It defaults to 1.

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

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-ratelimit
spec:
  rateLimit:
    burst: 100

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

http:
  middlewares:
    test-ratelimit:
      rateLimit:
        burst: 100

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

sourceCriterion

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 three parameters that configures how Traefik determines the client IP: depth, excludedIPs and ipv6Subnet.

!!! important "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, i.e. 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

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.

If ipStrategy.ipv6Subnet is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to.
See ipStrategy.ipv6Subnet for more details.

!!! example "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`     | `""`         |

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

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-ratelimit
spec:
  rateLimit:
    sourceCriterion:
      ipStrategy:
        depth: 2

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

http:
  middlewares:
    test-ratelimit:
      rateLimit:
        sourceCriterion:
          ipStrategy:
            depth: 2

[http.middlewares]
  [http.middlewares.test-ratelimit.rateLimit]
    [http.middlewares.test-ratelimit.rateLimit.sourceCriterion.ipStrategy]
      depth = 2

ipStrategy.excludedIPs

!!! important "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."

!!! important "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.

   !!! example "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.

   !!! example "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.

!!! example "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"` | `""`         |

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

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

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

http:
  middlewares:
    test-ratelimit:
      rateLimit:
        sourceCriterion:
          ipStrategy:
            excludedIPs:
              - "127.0.0.1/32"
              - "192.168.1.7"

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

ipStrategy.ipv6Subnet

This strategy applies to Depth and RemoteAddr strategy only. If ipv6Subnet is provided and the selected IP is IPv6, the IP is transformed into the first IP of the subnet it belongs to.

This is useful for grouping IPv6 addresses into subnets to prevent bypassing this middleware by obtaining a new IPv6.

• ipv6Subnet is ignored if its value is outside of 0-128 interval

!!! example "Example of ipv6Subnet"

If `ipv6Subnet` is provided, the IP is transformed in the following way.

| `IP`                      | `ipv6Subnet` | clientIP              |
|---------------------------|--------------|-----------------------|
| `"::abcd:1111:2222:3333"` | `64`         | `"::0:0:0:0"`         |
| `"::abcd:1111:2222:3333"` | `80`         | `"::abcd:0:0:0:0"`    |
| `"::abcd:1111:2222:3333"` | `96`         | `"::abcd:1111:0:0:0"` |

labels:
  - "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.ipv6Subnet=64"

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-ratelimit
spec:
  ratelimit:
    sourceCriterion:
      ipStrategy:
        ipv6Subnet: 64

- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.ipv6Subnet=64"

http:
  middlewares:
    test-ratelimit:
      ratelimit:
        sourceCriterion:
          ipStrategy:
            ipv6Subnet: 64

[http.middlewares]
  [http.middlewares.test-ratelimit.ratelimit]
    [http.middlewares.test-ratelimit.ratelimit.sourceCriterion.ipStrategy]
      ipv6Subnet = 64

sourceCriterion.requestHeaderName

Name of the header used to group incoming requests.

!!! important "If the header is not present, rate limiting will still be applied, but all requests without the specified header will be grouped together."

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

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-ratelimit
spec:
  rateLimit:
	sourceCriterion:
      requestHeaderName: username

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

http:
  middlewares:
    test-ratelimit:
      rateLimit:
        sourceCriterion:
          requestHeaderName: username

[http.middlewares]
  [http.middlewares.test-ratelimit.rateLimit]
    [http.middlewares.test-ratelimit.rateLimit.sourceCriterion]
      requestHeaderName = "username"

sourceCriterion.requestHost

Whether to consider the request host as the source.

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

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: test-ratelimit
spec:
  rateLimit:
    sourceCriterion:
      requestHost: true

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

http:
  middlewares:
    test-ratelimit:
      rateLimit:
        sourceCriterion:
          requestHost: true

[http.middlewares]
  [http.middlewares.test-ratelimit.rateLimit]
    [http.middlewares.test-ratelimit.rateLimit.sourceCriterion]
      requestHost = true