Add period for rate limiter middleware

docs/content/middlewares/ratelimit.md

@@ -3,7 +3,7 @@
 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.
+The RateLimit middleware ensures that services will receive a _fair_ number of requests, and allows one to define what fair is.
 
 ## Configuration Example
 
@@ -24,8 +24,8 @@ metadata:
   name: test-ratelimit
 spec:
   rateLimit:
-      average: 100
-      burst: 50
+    average: 100
+    burst: 50
 ```
 
 ```yaml tab="Consul Catalog"
@@ -74,25 +74,32 @@ http:
 
 ### `average`
 
-Average is the maximum rate, in requests/s, allowed for the given source.
-It defaults to 0, which means no rate limiting.
+`average` is the maximum rate, by default in requests by second, allowed for the 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.
 
 ```yaml tab="Docker"
+# 100 reqs/s
 labels:
   - "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
 ```
 
 ```yaml tab="Kubernetes"
+# 100 reqs/s
 apiVersion: traefik.containo.us/v1alpha1
 kind: Middleware
 metadata:
   name: test-ratelimit
 spec:
   rateLimit:
-      average: 100
+    average: 100
 ```
 
 ```yaml tab="Consul Catalog"
+# 100 reqs/s
 - "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
 ```
 
@@ -108,12 +115,14 @@ labels:
 ```
 
 ```toml tab="File (TOML)"
+# 100 reqs/s
 [http.middlewares]
   [http.middlewares.test-ratelimit.rateLimit]
     average = 100
 ```
 
 ```yaml tab="File (YAML)"
+# 100 reqs/s
 http:
   middlewares:
     test-ratelimit:
@@ -121,10 +130,78 @@ http:
         average: 100
 ```
 
+### `period`
+
+`period`, in combination with `average`, defines the actual maximum rate, such as:
+
+```go
+r = average / period
+```
+
+It defaults to `1` second.
+
+```yaml tab="Docker"
+# 6 reqs/minute
+labels:
+  - "traefik.http.middlewares.test-ratelimit.ratelimit.average=6"
+  - "traefik.http.middlewares.test-ratelimit.ratelimit.period=1m"
+```
+
+```yaml tab="Kubernetes"
+# 6 reqs/minute
+apiVersion: traefik.containo.us/v1alpha1
+kind: Middleware
+metadata:
+  name: test-ratelimit
+spec:
+  rateLimit:
+    period: 1m
+    average: 6
+```
+
+```yaml tab="Consul Catalog"
+# 6 reqs/minute
+- "traefik.http.middlewares.test-ratelimit.ratelimit.average=6"
+- "traefik.http.middlewares.test-ratelimit.ratelimit.period=1m"
+```
+
+```json tab="Marathon"
+"labels": {
+  "traefik.http.middlewares.test-ratelimit.ratelimit.average": "6",
+  "traefik.http.middlewares.test-ratelimit.ratelimit.period": "1m",
+}
+```
+
+```yaml tab="Rancher"
+# 6 reqs/minute
+labels:
+  - "traefik.http.middlewares.test-ratelimit.ratelimit.average=6"
+  - "traefik.http.middlewares.test-ratelimit.ratelimit.period=1m"
+```
+
+```toml tab="File (TOML)"
+# 6 reqs/minute
+[http.middlewares]
+  [http.middlewares.test-ratelimit.rateLimit]
+    average = 6
+    period = 1m
+```
+
+```yaml tab="File (YAML)"
+# 6 reqs/minute
+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.
+`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:
@@ -138,7 +215,7 @@ metadata:
   name: test-ratelimit
 spec:
   rateLimit:
-      burst: 100
+    burst: 100
 ```
 
 ```yaml tab="Consul Catalog"

docs/content/reference/dynamic-configuration/docker-labels.yml

@@ -88,6 +88,7 @@
 - "traefik.http.middlewares.middleware12.passtlsclientcert.info.subject.serialnumber=true"
 - "traefik.http.middlewares.middleware12.passtlsclientcert.pem=true"
 - "traefik.http.middlewares.middleware13.ratelimit.average=42"
+- "traefik.http.middlewares.middleware13.ratelimit.period=42"
 - "traefik.http.middlewares.middleware13.ratelimit.burst=42"
 - "traefik.http.middlewares.middleware13.ratelimit.sourcecriterion.ipstrategy.depth=42"
 - "traefik.http.middlewares.middleware13.ratelimit.sourcecriterion.ipstrategy.excludedips=foobar, foobar"

docs/content/reference/dynamic-configuration/file.toml

@@ -216,6 +216,7 @@
     [http.middlewares.Middleware13]
       [http.middlewares.Middleware13.rateLimit]
         average = 42
+        period = 42
         burst = 42
         [http.middlewares.Middleware13.rateLimit.sourceCriterion]
           requestHeaderName = "foobar"

docs/content/reference/dynamic-configuration/file.yaml

@@ -243,6 +243,7 @@ http:
     Middleware13:
       rateLimit:
         average: 42
+        period: 42
         burst: 42
         sourceCriterion:
           ipstrategy:

docs/content/reference/dynamic-configuration/kv-ref.md

@@ -102,6 +102,7 @@
 | `traefik/http/middlewares/Middleware12/passTLSClientCert/info/subject/serialNumber` | `true` |
 | `traefik/http/middlewares/Middleware12/passTLSClientCert/pem` | `true` |
 | `traefik/http/middlewares/Middleware13/rateLimit/average` | `42` |
+| `traefik/http/middlewares/Middleware13/rateLimit/period` | `42` |
 | `traefik/http/middlewares/Middleware13/rateLimit/burst` | `42` |
 | `traefik/http/middlewares/Middleware13/rateLimit/sourceCriterion/ipStrategy/depth` | `42` |
 | `traefik/http/middlewares/Middleware13/rateLimit/sourceCriterion/ipStrategy/excludedIPs/0` | `foobar` |

docs/content/reference/dynamic-configuration/marathon-labels.json

@@ -88,6 +88,7 @@
 "traefik.http.middlewares.middleware12.passtlsclientcert.info.subject.serialnumber": "true",
 "traefik.http.middlewares.middleware12.passtlsclientcert.pem": "true",
 "traefik.http.middlewares.middleware13.ratelimit.average": "42",
+"traefik.http.middlewares.middleware13.ratelimit.period": "42",
 "traefik.http.middlewares.middleware13.ratelimit.burst": "42",
 "traefik.http.middlewares.middleware13.ratelimit.sourcecriterion.ipstrategy.depth": "42",
 "traefik.http.middlewares.middleware13.ratelimit.sourcecriterion.ipstrategy.excludedips": "foobar, foobar",