traefik/docs/content/middlewares/ratelimit.md

344 lines
8.8 KiB
Markdown
Raw Normal View History

2019-04-08 15:14:08 +00:00
# RateLimit
To Control the Number of Requests Going to a Service
{: .subtitle }
The RateLimit middleware ensures that services will receive a _fair_ number of requests, and allows you define what is fair.
## Configuration Example
2019-04-08 15:14:08 +00:00
```yaml tab="Docker"
# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 50 requests is allowed.
2019-04-08 15:14:08 +00:00
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=50"
2019-04-08 15:14:08 +00:00
```
```yaml tab="Kubernetes"
# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 50 requests is allowed.
2019-04-08 15:14:08 +00:00
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: test-ratelimit
spec:
rateLimit:
average: 100
burst: 50
2019-04-08 15:14:08 +00:00
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-ratelimit.ratelimit.average": "100",
"traefik.http.middlewares.test-ratelimit.ratelimit.burst": "50"
}
```
2019-04-08 15:14:08 +00:00
```yaml tab="Rancher"
# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 50 requests is allowed.
2019-04-08 15:14:08 +00:00
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=50"
2019-04-08 15:14:08 +00:00
```
2019-07-22 07:58:04 +00:00
```toml tab="File (TOML)"
# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 50 requests is allowed.
2019-04-08 15:14:08 +00:00
[http.middlewares]
2019-07-01 09:30:05 +00:00
[http.middlewares.test-ratelimit.rateLimit]
average = 100
burst = 50
2019-04-08 15:14:08 +00:00
```
2019-07-22 07:58:04 +00:00
```yaml tab="File (YAML)"
# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 50 requests is allowed.
2019-07-22 07:58:04 +00:00
http:
middlewares:
test-ratelimit:
rateLimit:
average: 100
burst: 50
2019-07-22 07:58:04 +00:00
```
## Configuration Options
### `average`
Average is the maximum rate, in requests/s, allowed for the given source.
It defaults to 0, which means no rate limiting.
```yaml tab="Docker"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: test-ratelimit
spec:
rateLimit:
average: 100
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-ratelimit.ratelimit.average": "100",
}
```
```yaml tab="Rancher"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-ratelimit.rateLimit]
average = 100
```
```yaml tab="File (YAML)"
http:
middlewares:
test-ratelimit:
rateLimit:
average: 100
```
### `burst`
Burst is the maximum number of requests allowed to go through in the same arbitrarily small period of time.
It defaults to 1.
```yaml tab="Docker"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: test-ratelimit
spec:
rateLimit:
burst: 100
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-ratelimit.ratelimit.burst": "100",
}
```
```yaml tab="Rancher"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-ratelimit.rateLimit]
burst = 100
```
```yaml tab="File (YAML)"
http:
middlewares:
test-ratelimit:
rateLimit:
burst: 100
```
### `sourceCriterion`
SourceCriterion defines what criterion is used to group requests as originating from a common source.
The precedence order is `ipStrategy`, then `requestHeaderName`, then `requestHost`.
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 sets how Traefik will determine the client IP: `depth`, and `excludedIPs`.
##### `ipStrategy.depth`
The `depth` option tells Traefik to use the `X-Forwarded-For` header and take 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 will be empty.
2019-09-03 16:02:05 +00:00
- `depth` is ignored if its value is lesser than or equal to 0.
2019-09-23 12:32:04 +00:00
!!! example "Example of Depth & X-Forwarded-For"
If `depth` was equal to 2, and the request `X-Forwarded-For` header was `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` then the "real" client IP would be `"10.0.0.1"` (at depth 4) but the IP used as the criterion would be `"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` | `""` |
##### `ipStrategy.excludedIPs`
```yaml tab="Docker"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: test-ratelimit
spec:
rateLimit:
sourceCriterion:
ipStrategy:
excludedIPs:
- 127.0.0.1/32
- 192.168.1.7
```
```yaml tab="Rancher"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.ipstrategy.excludedips": "127.0.0.1/32, 192.168.1.7"
}
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-ratelimit.rateLimit]
[http.middlewares.test-ratelimit.rateLimit.sourceCriterion.ipStrategy]
excludedIPs = ["127.0.0.1/32", "192.168.1.7"]
```
```yaml tab="File (YAML)"
http:
middlewares:
test-ratelimit:
rateLimit:
sourceCriterion:
ipStrategy:
excludedIPs:
2019-09-23 15:00:06 +00:00
- "127.0.0.1/32"
- "192.168.1.7"
```
2019-09-23 12:32:04 +00:00
`excludedIPs` tells Traefik to scan the `X-Forwarded-For` header and pick the first IP not in the list.
!!! important "If `depth` is specified, `excludedIPs` is ignored."
!!! example "Example of ExcludedIPs & X-Forwarded-For"
| `X-Forwarded-For` | `excludedIPs` | clientIP |
|-----------------------------------------|-----------------------|--------------|
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"12.0.0.1,13.0.0.1"` | `"11.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"15.0.0.1,13.0.0.1"` | `"12.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.0.0.1,13.0.0.1"` | `"10.0.0.1,13.0.0.1"` | `"12.0.0.1"` |
| `"10.0.0.1,11.0.0.1,12.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"` | `""` |
#### `sourceCriterion.requestHeaderName`
Requests having the same value for the given header are grouped as coming from the same source.
```yaml tab="Docker"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requestheadername=username"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: test-ratelimit
spec:
rateLimit:
sourceCriterion:
requestHeaderName: username
```
```yaml tab="Rancher"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requestheadername=username"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requestheadername": "username"
}
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-ratelimit.rateLimit]
[http.middlewares.test-ratelimit.rateLimit.sourceCriterion]
requestHeaderName = "username"
```
```yaml tab="File (YAML)"
http:
middlewares:
test-ratelimit:
rateLimit:
sourceCriterion:
requestHeaderName: username
```
#### `sourceCriterion.requestHost`
Whether to consider the request host as the source.
```yaml tab="Docker"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requesthost=true"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: test-ratelimit
spec:
rateLimit:
sourceCriterion:
requestHost: true
```
```yaml tab="Rancher"
labels:
2019-09-23 15:00:06 +00:00
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requesthost=true"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requesthost": "true"
}
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-ratelimit.rateLimit]
[http.middlewares.test-ratelimit.rateLimit.sourceCriterion]
requestHost = true
```
```yaml tab="File (YAML)"
http:
middlewares:
test-ratelimit:
rateLimit:
sourceCriterion:
requestHost: true
2019-09-23 15:00:06 +00:00
```