1
0
Fork 0

doc: improve examples.

This commit is contained in:
Ludovic Fernandez 2019-07-22 09:58:04 +02:00 committed by Traefiker Bot
parent 8b4ba3cb67
commit 75c99a0491
69 changed files with 1256 additions and 552 deletions

View file

@ -38,13 +38,22 @@ labels:
- "traefik.http.middlewares.add-foo.addprefix.prefix=/foo"
```
```toml tab="File"
```toml tab="File (TOML)"
# Prefixing with /foo
[http.middlewares]
[http.middlewares.add-foo.addPrefix]
prefix = "/foo"
```
```yaml tab="File (YAML)"
# Prefixing with /foo
http:
middlewares:
add-foo:
addPrefix:
prefix: "/foo"
```
## Configuration Options
### `prefix`

View file

@ -44,7 +44,7 @@ labels:
- "traefik.http.middlewares.test-auth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
```
```toml tab="File"
```toml tab="File (TOML)"
# Declaring the user list
[http.middlewares]
[http.middlewares.test-auth.basicAuth]
@ -54,6 +54,17 @@ labels:
]
```
```yaml tab="File (YAML)"
# Declaring the user list
http:
middlewares:
test-auth:
basicAuth:
users:
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
```
## Configuration Options
### General
@ -119,12 +130,21 @@ spec:
}
```
```toml tab="File"
```toml tab="File (TOML)"
[http.middlewares.my-auth.basicAuth]
# ...
headerField = "X-WebAuth-User"
```
```yaml tab="File (YAML)"
http:
middlewares:
my-auth:
basicAuth:
# ...
headerField: "X-WebAuth-User"
```
### `removeHeader`
Set the `removeHeader` option to `true` to remove the authorization header before forwarding the request to your service. (Default value is `false`.)

View file

@ -42,13 +42,22 @@ labels:
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=250000"
```
```toml tab="File"
```toml tab="File (TOML)"
# Sets the maximum request body to 2Mb
[http.middlewares]
[http.middlewares.limit.buffering]
maxRequestBodyBytes = 250000
```
```yaml tab="File (YAML)"
# Sets the maximum request body to 2Mb
http:
middlewares:
limit:
buffering:
maxRequestBodyBytes: 250000
```
## Configuration Options
### `maxRequestBodyBytes`
@ -77,7 +86,7 @@ You can have the Buffering middleware replay the request with the help of the `r
!!! example "Retries once in case of a network error"
```
```toml
retryExpression = "IsNetworkError() && Attempts() < 2"
```

View file

@ -108,7 +108,7 @@ labels:
- "http.services.service1.loadbalancer.server.port=80"
```
```toml tab="File"
```toml tab="File (TOML)"
# ...
[http.routers]
[http.routers.router1]
@ -135,3 +135,43 @@ labels:
[[http.services.service1.loadBalancer.servers]]
url = "http://127.0.0.1:80"
```
```yaml tab="File (YAML)"
# ...
http:
routers:
router1:
service: service1
middlewares:
- secured
rule: "Host(`mydomain`)"
middlewares:
secured:
chain:
middlewares:
- https-only
- known-ips
- auth-users
auth-users:
basicAuth:
users:
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
https-only:
redirectScheme:
scheme: https
known-ips:
ipWhiteList:
sourceRange:
- "192.168.1.7"
- "127.0.0.1/32"
services:
service1:
loadBalancer:
servers:
- url: "http://127.0.0.1:80"
```

View file

@ -52,13 +52,22 @@ labels:
- "traefik.http.middlewares.latency-check.circuitbreaker.expression=LatencyAtQuantileMS(50.0) > 100"
```
```toml tab="File"
```toml tab="File (TOML)"
# Latency Check
[http.middlewares]
[http.middlewares.latency-check.circuitBreaker]
expression = "LatencyAtQuantileMS(50.0) > 100"
```
```yaml tab="File (YAML)"
# Latency Check
http:
middlewares:
latency-check:
circuitBreaker:
expression: "LatencyAtQuantileMS(50.0) > 100"
```
## Possible States
There are three possible states for your circuit breaker:

View file

@ -37,12 +37,20 @@ labels:
- "traefik.http.middlewares.test-compress.compress=true"
```
```toml tab="File"
```toml tab="File (TOML)"
# Enable gzip compression
[http.middlewares]
[http.middlewares.test-compress.compress]
```
```yaml tab="File (YAML)"
# Enable gzip compression
http:
middlewares:
test-compress:
compress: {}
```
## Notes
Responses are compressed when:

View file

@ -38,7 +38,7 @@ labels:
- "traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
```
```toml tab="File"
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-auth.digestAuth]
users = [
@ -47,6 +47,16 @@ labels:
]
```
```yaml tab="File (YAML)"
http:
middlewares:
test-auth:
digestAuth:
users:
- "test:traefik:a2688e031edb4be6a3797f3882655c05"
- "test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
```
!!! tip
Use `htdigest` to generate passwords.
@ -115,12 +125,21 @@ labels:
}
```
```toml tab="File"
```toml tab="File (TOML)"
[http.middlewares.my-auth.digestAuth]
# ...
headerField = "X-WebAuth-User"
```
```yaml tab="File (YAML)"
http:
middlewares:
my-auth:
digestAuth:
# ...
headerField: "X-WebAuth-User"
```
### `removeHeader`
Set the `removeHeader` option to `true` to remove the authorization header before forwarding the request to your service. (Default value is `false`.)

View file

@ -49,7 +49,7 @@ labels:
- "traefik.http.middlewares.test-errorpage.errors.query=/{status}.html"
```
```toml tab="File"
```toml tab="File (TOML)"
# Custom Error Page for 5XX
[http.middlewares]
[http.middlewares.test-errorpage.errors]
@ -61,6 +61,21 @@ labels:
# ... definition of error-handler-service and my-service
```
```yaml tab="File (YAML)"
# Custom Error Page for 5XX
http:
middlewares:
test-errorpage:
errors:
status:
- "500-599"
service: serviceError
query: "/{status}.html"
[http.services]
# ... definition of error-handler-service and my-service
```
!!! note
In this example, the error page URL is based on the status code (`query=/{status}.html)`.

View file

@ -69,7 +69,7 @@ labels:
- "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader=true"
```
```toml tab="File"
```toml tab="File (TOML)"
# Forward authentication to authserver.com
[http.middlewares]
[http.middlewares.test-auth.forwardAuth]
@ -84,6 +84,24 @@ labels:
key = "path/to/foo.key"
```
```yaml tab="File (YAML)"
# Forward authentication to authserver.com
http:
middlewares:
test-auth:
forwardAuth:
address: "https://authserver.com/auth"
trustForwardHeader: true
authResponseHeaders:
- "X-Auth-User"
- "X-Secret"
tls:
ca: "path/to/local.crt"
caOptional: true
cert: "path/to/foo.cert"
key: "path/to/foo.key"
```
## Configuration Options
### `address`

View file

@ -16,7 +16,7 @@ Add the `X-Script-Name` header to the proxied request and the `X-Custom-Response
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.testHeader.headers.customrequestheaders.X-Script-Name=test"
- "traefik.http.middlewares.testHeader.headers.customresponseheaders.X-Custom-Response-Header=True"
- "traefik.http.middlewares.testHeader.headers.customresponseheaders.X-Custom-Response-Header=value"
```
```yaml tab="Kubernetes"
@ -29,29 +29,40 @@ spec:
customRequestHeaders:
X-Script-Name: "test"
customResponseHeaders:
X-Custom-Response-Header: "True"
X-Custom-Response-Header: "value"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name": "test",
"traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header": "True"
"traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header": "value"
}
```
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
- "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header=True"
- "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header=value"
```
```toml tab="File"
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.testHeader.headers]
[http.middlewares.testHeader.headers.customRequestHeaders]
X-Script-Name = "test"
[http.middlewares.testHeader.headers.customResponseHeaders]
X-Custom-Response-Header = "True"
X-Custom-Response-Header = "value"
```
```yaml tab="File (YAML)"
http:
middlewares:
testHeader:
headers:
customRequestHeaders:
X-Script-Name: "test"
customResponseHeaders:
X-Custom-Response-Header: "value"
```
### Adding and Removing Headers
@ -86,7 +97,7 @@ labels:
}
```
```toml tab="File"
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.testHeader.headers]
[http.middlewares.testHeader.headers.customRequestHeaders]
@ -96,6 +107,18 @@ labels:
X-Custom-Response-Header = "" # Removes
```
```yaml tab="File (YAML)"
http:
middlewares:
testHeader:
headers:
customRequestHeaders:
X-Script-Name: "test" # Adds
X-Custom-Request-Header: "" # Removes
customResponseHeaders:
X-Custom-Response-Header: "" # Removes
```
### Using Security Headers
Security related headers (HSTS headers, SSL redirection, Browser XSS filter, etc) can be added and configured per frontend in a similar manner to the custom headers above.
@ -131,13 +154,22 @@ labels:
}
```
```toml tab="File"
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.testHeader.headers]
FrameDeny = true
SSLRedirect = true
```
```yaml tab="File (YAML)"
http:
middlewares:
testHeader:
headers:
FrameDeny: true
SSLRedirect: true
```
### CORS Headers
CORS (Cross-Origin Resource Sharing) headers can be added and configured per frontend in a similar manner to the custom headers above.
@ -184,7 +216,7 @@ labels:
}
```
```toml tab="File"
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.testHeader.headers]
accessControlAllowMethods= ["GET", "OPTIONS", "PUT"]
@ -193,6 +225,20 @@ labels:
addVaryHeader = true
```
```yaml tab="File (YAML)"
http:
middlewares:
testHeader:
headers:
accessControlAllowMethod:
- GET
- OPTIONS
- PUT
accessControlAllowOrigin: "origin-list-or-null"
accessControlMaxAge: 100
addVaryHeader: true
```
## Configuration Options
### General

View file

@ -39,13 +39,24 @@ labels:
- "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
```
```toml tab="File"
```toml tab="File (TOML)"
# Accepts request from defined IP
[http.middlewares]
[http.middlewares.test-ipwhitelist.ipWhiteList]
sourceRange = ["127.0.0.1/32", "192.168.1.7"]
```
```yaml tab="File (YAML)"
# Accepts request from defined IP
http:
middlewares:
test-ipwhitelist:
ipWhiteList:
sourceRange:
- "127.0.0.1/32"
- "192.168.1.7"
```
## Configuration Options
### `sourceRange`
@ -108,7 +119,7 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
}
```
```toml tab="File"
```toml tab="File (TOML)"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
[http.middlewares]
[http.middlewares.test-ipwhitelist.ipWhiteList]
@ -116,6 +127,19 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
[http.middlewares.test-ipwhitelist.ipWhiteList.ipStrategy]
depth = 2
```
```yaml tab="File (YAML)"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
http:
middlewares:
test-ipwhitelist:
ipWhiteList:
sourceRange:
- "127.0.0.1/32"
- "192.168.1.7"
ipStrategy:
depth: 2
```
!!! note
@ -171,10 +195,22 @@ labels:
}
```
```toml tab="File"
```toml tab="File (TOML)"
# Exclude from `X-Forwarded-For`
[http.middlewares]
[http.middlewares.test-ipwhitelist.ipWhiteList]
[http.middlewares.test-ipwhitelist.ipWhiteList.ipStrategy]
excludedIPs = ["127.0.0.1/32", "192.168.1.7"]
```
```yaml tab="File (YAML)"
# Exclude from `X-Forwarded-For`
http:
middlewares:
test-ipwhitelist:
ipWhiteList:
ipStrategy:
excludedIPs:
- "127.0.0.1/32"
- "192.168.1.7"
```

View file

@ -37,23 +37,32 @@ labels:
- "traefik.http.middlewares.test-maxconn.maxconn.amount=10"
```
```toml tab="File"
```toml tab="File (TOML)"
# Limiting to 10 simultaneous connections
[http.middlewares]
[http.middlewares.test-maxconn.maxConn]
amount = 10
```
```yaml tab="File (YAML)"
# Limiting to 10 simultaneous connections
http:
middlewares:
test-maxconn:
maxConn:
amount: 10
```
## Configuration Options
### `amount`
The `amount` option defines the maximum amount of allowed simultaneous connections.
The middleware will return an `HTTP 429 Too Many Requests` if there are already `amount` requests in progress (based on the same `extractorfunc` strategy).
The middleware will return an `HTTP 429 Too Many Requests` if there are already `amount` requests in progress (based on the same `extractorFunc` strategy).
### extractorfunc
### `extractorFunc`
The `extractorfunc` defines the strategy used to categorize requests.
The `extractorFunc` defines the strategy used to categorize requests.
The possible values are:

View file

@ -79,8 +79,8 @@ labels:
- "traefik.http.router.router1.middlewares=foo-add-prefix@rancher"
```
```toml tab="File"
# As Toml Configuration File
```toml tab="File (TOML)"
# As TOML Configuration File
[http.routers]
[http.routers.router1]
service = "myService"
@ -99,6 +99,28 @@ labels:
url = "http://127.0.0.1:80"
```
```yaml tab="File (YAML)"
# As YAML Configuration File
http:
routers:
router1:
service: myService
middlewares:
- "foo-add-prefix"
rule: "Host(`example.com`)"
middlewares:
foo-add-prefix:
addPrefix:
prefix: "/foo"
services:
service1:
loadBalancer:
servers:
- url: "http://127.0.0.1:80"
```
## Provider Namespace
When you declare a middleware, it lives in its provider namespace.
@ -124,11 +146,19 @@ and therefore this specification would be ignored even if present.
Declaring the add-foo-prefix in the file provider.
```toml
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.add-foo-prefix.addPrefix]
prefix = "/foo"
```
```yaml tab="File (YAML)"
http:
middlewares:
add-foo-prefix:
addPrefix:
prefix: "/foo"
```
Using the add-foo-prefix middleware from other providers:

View file

@ -39,13 +39,22 @@ labels:
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.pem=true"
```
```toml tab="File"
```toml tab="File (TOML)"
# Pass the escaped pem in the `X-Forwarded-Tls-Client-Cert` header.
[http.middlewares]
[http.middlewares.test-passtlsclientcert.passTLSClientCert]
pem = true
```
```yaml tab="File (YAML)"
# Pass the escaped pem in the `X-Forwarded-Tls-Client-Cert` header.
http:
middlewares:
test-passtlsclientcert:
passTLSClientCert:
pem: true
```
??? example "Pass the escaped pem in the `X-Forwarded-Tls-Client-Cert` header"
```yaml tab="Docker"
@ -144,7 +153,7 @@ labels:
}
```
```toml tab="File"
```toml tab="File (TOML)"
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
[http.middlewares]
[http.middlewares.test-passtlsclientcert.passTLSClientCert]
@ -170,6 +179,34 @@ labels:
domainComponent = true
```
```yaml tab="File (YAML)"
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
http:
middlewares:
test-passtlsclientcert:
passTLSClientCert:
info:
notAfter: true
notBefore: true
sans: true
subject:
country: true
province: true
locality: true
organization: true
commonName: true
serialNumber: true
domainComponent: true
issuer:
country: true
province: true
locality: true
organization: true
commonName: true
serialNumber: true
domainComponent: true
```
## Configuration Options
### General

View file

@ -73,12 +73,12 @@ labels:
```
```toml tab="File"
```toml tab="File (TOML)"
# Here, an average of 5 requests every 3 seconds is allowed and an average of 100 requests every 10 seconds.
# These can "burst" up to 10 and 200 in each period, respectively.
[http.middlewares]
[http.middlewares.test-ratelimit.rateLimit]
extractorfunc = "client.ip"
extractorFunc = "client.ip"
[http.middlewares.test-ratelimit.rateLimit.rateSet.rate0]
period = "10s"
@ -91,11 +91,30 @@ labels:
burst = 10
```
```yaml tab="File (YAML)"
# Here, an average of 5 requests every 3 seconds is allowed and an average of 100 requests every 10 seconds.
# These can "burst" up to 10 and 200 in each period, respectively.
http:
middlewares:
test-ratelimit:
rateLimit:
extractorFunc: "client.ip"
rateSet:
rate0:
period: "10s"
average: 100
burst: 200
rate1:
period: "3s"
average: 5
burst: 10
```
## Configuration Options
### `extractorfunc`
### `extractorFunc`
The `extractorfunc` option defines the strategy used to categorize requests.
The `extractorFunc` option defines the strategy used to categorize requests.
The possible values are:

View file

@ -42,7 +42,7 @@ labels:
- "traefik.http.middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/$1"
```
```toml tab="File"
```toml tab="File (TOML)"
# Redirect with domain replacement
[http.middlewares]
[http.middlewares.test-redirectregex.redirectRegex]
@ -50,6 +50,16 @@ labels:
replacement = "http://mydomain/$1"
```
```yaml tab="File (YAML)"
# Redirect with domain replacement
http:
middlewares:
test-redirectregex:
redirectRegex:
regex: "^http://localhost/(.*)"
replacement: "http://mydomain/$1"
```
## Configuration Options
### `permanent`

View file

@ -38,13 +38,22 @@ labels:
- "traefik.http.middlewares.test-redirectscheme.redirectscheme.scheme=https"
```
```toml tab="File"
```toml tab="File (TOML)"
# Redirect to https
[http.middlewares]
[http.middlewares.test-redirectscheme.redirectScheme]
scheme = "https"
```
```yaml tab="File (YAML)"
# Redirect to https
http:
middlewares:
test-redirectscheme:
redirectScheme:
scheme: https
```
## Configuration Options
### `permanent`

View file

@ -38,13 +38,22 @@ labels:
- "traefik.http.middlewares.test-replacepath.replacepath.path=/foo"
```
```toml tab="File"
```toml tab="File (TOML)"
# Replace the path by /foo
[http.middlewares]
[http.middlewares.test-replacepath.replacePath]
path = "/foo"
```
```yaml tab="File (YAML)"
# Replace the path by /foo
http:
middlewares:
test-replacepath:
replacePath:
path: "/foo"
```
## Configuration Options
### General

View file

@ -42,7 +42,7 @@ labels:
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.replacement=/bar/$1"
```
```toml tab="File"
```toml tab="File (TOML)"
# Redirect with domain replacement
[http.middlewares]
[http.middlewares.test-replacepathregex.replacePathRegex]
@ -50,6 +50,16 @@ labels:
replacement = "/bar/$1"
```
```yaml tab="File (YAML)"
# Redirect with domain replacement
http:
middlewares:
test-replacepathregex:
replacePathRegex:
regex: "^/foo/(.*)"
replacement: "/bar/$1"
```
## Configuration Options
### General

View file

@ -38,13 +38,22 @@ labels:
- "traefik.http.middlewares.test-retry.retry.attempts=4"
```
```toml tab="File"
```toml tab="File (TOML)"
# Retry to send request 4 times
[http.middlewares]
[http.middlewares.test-retry.retry]
attempts = 4
```
```yaml tab="File (YAML)"
# Retry to send request 4 times
http:
middlewares:
test-retry:
retry:
attempts: 4
```
## Configuration Options
### `attempts`

View file

@ -40,13 +40,24 @@ labels:
- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar, /fiibar"
```
```toml tab="File"
```toml tab="File (TOML)"
# Strip prefix /foobar and /fiibar
[http.middlewares]
[http.middlewares.test-stripprefix.stripPrefix]
prefixes = ["/foobar", "/fiibar"]
```
```yaml tab="File (YAML)"
# Strip prefix /foobar and /fiibar
http:
middlewares:
test-stripprefix:
stripPrefix:
prefixes:
- "/foobar"
- "/fiibar"
```
## Configuration Options
### General

View file

@ -38,11 +38,20 @@ labels:
- "traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=^/foo/(.*)",
```
```toml tab="File"
```toml tab="File (TOML)"
# Replace the path by /foo
[http.middlewares]
[http.middlewares.test-stripprefixregex.stripPrefixRegex]
regex: "^/foo/(.*)"
regex = "^/foo/(.*)"
```
```yaml tab="File (YAML)"
# Replace the path by /foo
http:
middlewares:
test-stripprefixregex:
stripPrefixRegex:
regex: "^/foo/(.*)"
```
## Configuration Options