baalajimaestro/traefik
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Merge branch 'v2.0' into master

Browse source
This commit is contained in:
Fernandez Ludovic 2019-09-23 17:26:52 +02:00
parent 56e0580aa5 17480abe85
commit 2471f893e7
63 changed files with 3923 additions and 1472 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
README.md
View file

@ -33,7 +33,7 @@ Pointing Traefik at your orchestrator should be the _only_ configuration step yo
---
:warning: Please be aware that the old configurations for Traefik v1.X are NOT compatible with the v2.X config as of now. If you're testing out v2, please ensure you are using a [v2 configuration](https://docs.traefik.io/v2.0/).
:warning: Please be aware that the old configurations for Traefik v1.X are NOT compatible with the v2.X config as of now. If you're running v2, please ensure you are using a [v2 configuration](https://docs.traefik.io/).
## Overview
@ -69,18 +69,11 @@ _(But if you'd rather configure some of your routes manually, Traefik supports t
## Supported Backends
- [Docker](https://docs.traefik.io/configuration/backends/docker) / [Swarm mode](https://docs.traefik.io/configuration/backends/docker#docker-swarm-mode)
- [Kubernetes](https://docs.traefik.io/configuration/backends/kubernetes)
- [Mesos](https://docs.traefik.io/configuration/backends/mesos) / [Marathon](https://docs.traefik.io/configuration/backends/marathon)
- [Rancher](https://docs.traefik.io/configuration/backends/rancher) (API, Metadata)
- [Azure Service Fabric](https://docs.traefik.io/configuration/backends/servicefabric)
- [Consul Catalog](https://docs.traefik.io/configuration/backends/consulcatalog)
- [Consul](https://docs.traefik.io/configuration/backends/consul) / [Etcd](https://docs.traefik.io/configuration/backends/etcd) / [Zookeeper](https://docs.traefik.io/configuration/backends/zookeeper) / [BoltDB](https://docs.traefik.io/configuration/backends/boltdb)
- [Eureka](https://docs.traefik.io/configuration/backends/eureka)
- [Amazon ECS](https://docs.traefik.io/configuration/backends/ecs)
- [Amazon DynamoDB](https://docs.traefik.io/configuration/backends/dynamodb)
- [Docker](https://docs.traefik.io/providers/docker/) / [Swarm mode](https://docs.traefik.io/providers/docker/)
- [Kubernetes](https://docs.traefik.io/providers/kubernetes-crd/)
- [Marathon](https://docs.traefik.io/providers/marathon/)
- [Rancher](https://docs.traefik.io/providers/rancher/) (Metadata)
- [File](https://docs.traefik.io/configuration/backends/file)
- [Rest](https://docs.traefik.io/configuration/backends/rest)
## Quickstart
@ -97,7 +90,7 @@ You can access the simple HTML frontend of Traefik.
You can find the complete documentation at [https://docs.traefik.io](https://docs.traefik.io).
A collection of contributions around Traefik can be found at [https://awesome.traefik.io](https://awesome.traefik.io).
:warning: If you're testing out v2, please ensure you are using the [v2 documentation](https://docs.traefik.io/v2.0/).
:warning: If you're testing out v2, please ensure you are using the [v2 documentation](https://docs.traefik.io/).
## Support
@ -128,7 +121,7 @@ git clone https://github.com/containous/traefik
## Introductory Videos
:warning: Please be aware that these videos are for v1.X. The old configurations for Traefik v1.X are NOT compatible with Traefik v2. If you're testing out v2, please ensure you are using a [v2 configuration](https://docs.traefik.io/v2.0/).
:warning: Please be aware that these videos are for v1.X. The old configurations for Traefik v1.X are NOT compatible with Traefik v2. If you're running v2, please ensure you are using a [v2 configuration](https://docs.traefik.io/).
Here is a talk given by [Emile Vauge](https://github.com/emilevauge) at GopherCon 2017.
You will learn Traefik basics in less than 10 minutes.

81
docs/content/contributing/data-collection.md
View file

@ -42,54 +42,51 @@ Once a day (the first call begins 10 minutes after the start of Traefik), we col
- a hash of the configuration
- an **anonymized version** of the static configuration (token, user name, password, URL, IP, domain, email, etc, are removed).
!!! note
We do not collect the dynamic configuration information (routers & services).
We do not collect these data to run advertising programs.
We do not sell these data to third-parties.
!!! info
- We do not collect the dynamic configuration information (routers & services).
- We do not collect this data to run advertising programs.
- We do not sell this data to third-parties.
### Example of Collected Data
??? example "Original configuration"
```toml tab="Original configuration"
[entryPoints]
[entryPoints.web]
address = ":80"
```toml
[entryPoints]
[entryPoints.web]
address = ":80"
[api]
[providers.docker]
endpoint = "tcp://10.10.10.10:2375"
exposedByDefault = true
swarmMode = true
[providers.docker.TLS]
ca = "dockerCA"
cert = "dockerCert"
key = "dockerKey"
insecureSkipVerify = true
```
[api]
??? example "Resulting Obfuscated Configuration"
[providers.docker]
endpoint = "tcp://10.10.10.10:2375"
exposedByDefault = true
swarmMode = true
```toml
[entryPoints]
[entryPoints.web]
address = ":80"
[api]
[providers.docker]
endpoint = "xxxx"
exposedByDefault = true
swarmMode = true
[providers.docker.TLS]
ca = "xxxx"
cert = "xxxx"
key = "xxxx"
insecureSkipVerify = false
```
[providers.docker.TLS]
ca = "dockerCA"
cert = "dockerCert"
key = "dockerKey"
insecureSkipVerify = true
```
```toml tab="Resulting Obfuscated Configuration"
[entryPoints]
[entryPoints.web]
address = ":80"
[api]
[providers.docker]
endpoint = "xxxx"
exposedByDefault = true
swarmMode = true
[providers.docker.TLS]
ca = "xxxx"
cert = "xxxx"
key = "xxxx"
insecureSkipVerify = false
```
## The Code for Data Collection

4
docs/content/getting-started/concepts.md
View file

@ -23,11 +23,11 @@ The opposite is true: when you remove a service from your infrastructure, the ro
You no longer need to create and synchronize configuration files cluttered with IP addresses or other rules.
!!! note "Many different rules"
!!! info "Many different rules"
In the example above, we used the request [path](../routing/routers/index.md#rule) to determine which service was in charge, but of course you can use many other different [rules](../routing/routers/index.md#rule).
!!! note "Updating the requests"
!!! info "Updating the requests"
In the [middleware](../middlewares/overview.md) section, you can learn about how to update the requests before forwarding them to the services.

18
docs/content/getting-started/configuration-overview.md
View file

@ -21,23 +21,25 @@ This configuration can change and is seamlessly hot-reloaded, without any reques
## The Dynamic Configuration
Traefik gets its _dynamic configuration_ from [providers](../providers/overview.md): whether an orchestrator, a service registry, or a plain old configuration file. Since this configuration is specific to your infrastructure choices, we invite you to refer to the [dedicated section of this documentation](../providers/overview.md).
Traefik gets its _dynamic configuration_ from [providers](../providers/overview.md): whether an orchestrator, a service registry, or a plain old configuration file.
!!! Note
Since this configuration is specific to your infrastructure choices, we invite you to refer to the [dedicated section of this documentation](../routing/overview.md).
!!! info ""
In the [Quick Start example](../getting-started/quick-start.md), the dynamic configuration comes from docker in the form of labels attached to your containers.
!!! Note
!!! info "HTTPS Certificates also belong to the dynamic configuration."
HTTPS Certificates also belong to the dynamic configuration. You can add / update / remove them without restarting your Traefik instance.
You can add / update / remove them without restarting your Traefik instance.
## The Static Configuration
There are three different, mutually exclusive, ways to define static configuration options in Traefik:
There are three different, **mutually exclusive** (e.g. you can use only one at the same time), ways to define static configuration options in Traefik:
- In a configuration file
- In the command-line arguments
- As environment variables
1. In a configuration file
1. In the command-line arguments
1. As environment variables
These ways are evaluated in the order listed above.

8
docs/content/getting-started/install-traefik.md
View file

@ -10,7 +10,7 @@ You can install Traefik with the following flavors:
Choose one of the [official Docker images](https://hub.docker.com/_/traefik) and run it with the [sample configuration file](https://raw.githubusercontent.com/containous/traefik/v2.0/traefik.sample.toml):
```shell
```bash
docker run -d -p 8080:8080 -p 80:80 \
-v $PWD/traefik.toml:/etc/traefik/traefik.toml traefik:v2.0
```
@ -21,14 +21,14 @@ For more details, go to the [Docker provider documentation](../providers/docker.
* Prefer a fixed version than the latest that could be an unexpected version.
ex: `traefik:v2.0.0`
* Docker images comes in 2 flavors: scratch based or alpine based.
* Docker images are based from the [Alpine Linux Official image](https://hub.docker.com/_/alpine).
* All the orchestrator using docker images could fetch the official Traefik docker image.
## Use the Binary Distribution
Grab the latest binary from the [releases](https://github.com/containous/traefik/releases) page.
??? tip "Check the integrity of the downloaded file"
??? info "Check the integrity of the downloaded file"
```bash tab="Linux"
# Compare this value to the one found in traefik-${traefik_version}_checksums.txt
@ -45,7 +45,7 @@ Grab the latest binary from the [releases](https://github.com/containous/traefik
Get-FileHash ./traefik_${traefik_version}_windows_${arch}.zip -Algorithm SHA256
```
??? tip "Extract the downloaded archive"
??? info "Extract the downloaded archive"
```bash tab="Linux"
tar -zxvf traefik_${traefik_version}_linux_${arch}.tar.gz

18
docs/content/https/acme.md
View file

@ -23,7 +23,7 @@ You can configure Traefik to use an ACME provider (like Let's Encrypt) for autom
[certificatesResolvers.sample.acme]
email = "your-email@your-domain.org"
storage = "acme.json"
[acme.httpChallenge]
[certificatesResolvers.sample.acme.httpChallenge]
# used during the challenge
entryPoint = "web"
```
@ -56,6 +56,8 @@ You can configure Traefik to use an ACME provider (like Let's Encrypt) for autom
--certificatesResolvers.sample.acme.httpChallenge.entryPoint=web
```
!!! important "Defining a certificates resolver does not result in all routers automatically using it. Each router that is supposed to use the resolver must [reference](../routing/routers/index.md#certresolver) it."
??? note "Configuration Reference"
There are many available options for ACME.
@ -79,11 +81,13 @@ Traefik automatically tracks the expiry date of ACME certificates it generates.
If there are less than 30 days remaining before the certificate expires, Traefik will attempt to renew it automatically.
!!! note
!!! info ""
Certificates that are no longer used may still be renewed, as Traefik does not currently check if the certificate is being used before renewing.
## The Different ACME Challenges
!!! important "Defining a certificates resolver does not result in all routers automatically using it. Each router that is supposed to use the resolver must [reference](../routing/routers/index.md#certresolver) it."
### `tlsChallenge`
Use the `TLS-ALPN-01` challenge to generate and renew ACME certificates by provisioning a TLS certificate.
@ -158,7 +162,7 @@ when using the `HTTP-01` challenge, `certificatesResolvers.sample.acme.httpChall
--certificatesResolvers.sample.acme.httpChallenge.entryPoint=web
```
!!! note
!!! info ""
Redirection is fully compatible with the `HTTP-01` challenge.
### `dnsChallenge`
@ -274,7 +278,7 @@ For example, `CF_API_EMAIL_FILE=/run/secrets/traefik_cf-api-email` could be used
[^3]: [google/default.go](https://github.com/golang/oauth2/blob/36a7019397c4c86cf59eeab3bc0d188bac444277/google/default.go#L61-L76)
[^4]: `docker stack` remark: there is no way to support terminal attached to container when deploying with `docker stack`, so you might need to run container with `docker run -it` to generate certificates using `manual` provider.
!!! note "`delayBeforeCheck`"
!!! info "`delayBeforeCheck`"
By default, the `provider` verifies the TXT record _before_ letting ACME verify.
You can delay this operation by specifying a delay (in seconds) with `delayBeforeCheck` (value must be greater than zero).
This option is useful when internal networks block external DNS queries.
@ -299,8 +303,8 @@ certificatesResolvers:
dnsChallenge:
# ...
resolvers:
- "1.1.1.1:53"
- "8.8.8.8:53"
- "1.1.1.1:53"
- "8.8.8.8:53"
```
```bash tab="CLI"
@ -394,5 +398,5 @@ If Let's Encrypt is not reachable, the following certificates will apply:
1. Expired ACME certificates
1. Provided certificates
!!! note
!!! important
For new (sub)domains which need Let's Encrypt authentication, the default Traefik certificate will be used until Traefik is restarted.

226
docs/content/https/tls.md
View file

@ -13,7 +13,9 @@ See the [Let's Encrypt](./acme.md) page.
To add / remove TLS certificates, even when Traefik is already running, their definition can be added to the [dynamic configuration](../getting-started/configuration-overview.md), in the `[[tls.certificates]]` section:
```toml tab="TOML"
```toml tab="File (TOML)"
# Dynamic configuration
[[tls.certificates]]
certFile = "/path/to/domain.cert"
keyFile = "/path/to/domain.key"
@ -23,30 +25,37 @@ To add / remove TLS certificates, even when Traefik is already running, their de
keyFile = "/path/to/other-domain.key"
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
# Dynamic configuration
tls:
certificates:
- certFile: /path/to/domain.cert
keyFile: /path/to/domain.key
- certFile: /path/to/other-domain.cert
keyFile: /path/to/other-domain.key
- certFile: /path/to/domain.cert
keyFile: /path/to/domain.key
- certFile: /path/to/other-domain.cert
keyFile: /path/to/other-domain.key
```
!!! important "File Provider Only"
!!! important "Restriction"
In the above example, we've used the [file provider](../providers/file.md) to handle these definitions.
It is the only available method to configure the certificates (as well as the options and the stores).
However, in [Kubernetes](../providers/kubernetes-crd.md), the certificates can and must be provided by [secrets](../routing/providers/kubernetes-crd.md#tls).
## Certificates Stores
In Traefik, certificates are grouped together in certificates stores, which are defined as such:
```toml tab="TOML"
```toml tab="File (TOML)"
# Dynamic configuration
[tls.stores]
[tls.stores.default]
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
# Dynamic configuration
tls:
stores:
default: {}
@ -59,7 +68,9 @@ tls:
In the `tls.certificates` section, a list of stores can then be specified to indicate where the certificates should be stored:
```toml tab="TOML"
```toml tab="File (TOML)"
# Dynamic configuration
[[tls.certificates]]
certFile = "/path/to/domain.cert"
keyFile = "/path/to/domain.key"
@ -72,17 +83,19 @@ In the `tls.certificates` section, a list of stores can then be specified to ind
keyFile = "/path/to/other-domain.key"
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
# Dynamic configuration
tls:
certificates:
- certFile: /path/to/domain.cert
keyFile: /path/to/domain.key
stores:
- default
# Note that since no store is defined,
# the certificate below will be stored in the `default` store.
- certFile: /path/to/other-domain.cert
keyFile: /path/to/other-domain.key
- certFile: /path/to/domain.cert
keyFile: /path/to/domain.key
stores:
- default
# Note that since no store is defined,
# the certificate below will be stored in the `default` store.
- certFile: /path/to/other-domain.cert
keyFile: /path/to/other-domain.key
```
!!! important "Restriction"
@ -94,7 +107,9 @@ tls:
Traefik can use a default certificate for connections without a SNI, or without a matching domain.
This default certificate should be defined in a TLS store:
```toml tab="TOML"
```toml tab="File (TOML)"
# Dynamic configuration
[tls.stores]
[tls.stores.default]
[tls.stores.default.defaultCertificate]
@ -102,7 +117,9 @@ This default certificate should be defined in a TLS store:
keyFile = "path/to/cert.key"
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
# Dynamic configuration
tls:
stores:
default:
@ -119,7 +136,9 @@ The TLS options allow one to configure some parameters of the TLS connection.
### Minimum TLS Version
```toml tab="TOML"
```toml tab="File (TOML)"
# Dynamic configuration
[tls.options]
[tls.options.default]
@ -129,7 +148,9 @@ The TLS options allow one to configure some parameters of the TLS connection.
minVersion = "VersionTLS13"
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
# Dynamic configuration
tls:
options:
default:
@ -139,6 +160,105 @@ tls:
minVersion: VersionTLS13
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: default
namespace: default
spec:
minVersion: VersionTLS12
---
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: mintls13
namespace: default
spec:
minVersion: VersionTLS13
```
### Cipher Suites
See [cipherSuites](https://godoc.org/crypto/tls#pkg-constants) for more information.
```toml tab="File (TOML)"
# Dynamic configuration
[tls.options]
[tls.options.default]
cipherSuites = [
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
"TLS_RSA_WITH_AES_256_GCM_SHA384"
]
```
```yaml tab="File (YAML)"
# Dynamic configuration
tls:
options:
default:
cipherSuites:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: default
namespace: default
spec:
cipherSuites:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
```
!!! important "TLS 1.3"
Cipher suites defined for TLS 1.2 and below cannot be used in TLS 1.3, and vice versa. (<https://tools.ietf.org/html/rfc8446>)
With TLS 1.3, the cipher suites are not configurable (all supported cipher suites are safe in this case).
<https://golang.org/doc/go1.12#tls_1_3>
### Strict SNI Checking
With strict SNI checking, Traefik won't allow connections from clients connections
that do not specify a server_name extension.
```toml tab="File (TOML)"
# Dynamic configuration
[tls.options]
[tls.options.default]
sniStrict = true
```
```yaml tab="File (YAML)"
# Dynamic configuration
tls:
options:
default:
sniStrict: true
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: default
namespace: default
spec:
sniStrict: true
```
### Client Authentication (mTLS)
Traefik supports mutual authentication, through the `clientAuth` section.
@ -153,7 +273,9 @@ The `clientAuth.clientAuthType` option governs the behaviour as follows:
- `VerifyClientCertIfGiven`: if a certificate is provided, verifies if it is signed by a CA listed in `clientAuth.caFiles`. Otherwise proceeds without any certificate.
- `RequireAndVerifyClientCert`: requires a certificate, which must be signed by a CA listed in `clientAuth.caFiles`.
```toml tab="TOML"
```toml tab="File (TOML)"
# Dynamic configuration
[tls.options]
[tls.options.default]
[tls.options.default.clientAuth]
@ -162,54 +284,30 @@ The `clientAuth.clientAuthType` option governs the behaviour as follows:
clientAuthType = "RequireAndVerifyClientCert"
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
# Dynamic configuration
tls:
options:
default:
clientAuth:
# in PEM format. each file can contain multiple CAs.
caFiles:
- tests/clientca1.crt
- tests/clientca2.crt
- tests/clientca1.crt
- tests/clientca2.crt
clientAuthType: RequireAndVerifyClientCert
```
### Cipher Suites
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: default
namespace: default
See [cipherSuites](https://godoc.org/crypto/tls#pkg-constants) for more information.
```toml tab="TOML"
[tls.options]
[tls.options.default]
cipherSuites = [
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
"TLS_RSA_WITH_AES_256_GCM_SHA384"
]
```
```yaml tab="YAML"
tls:
options:
default:
cipherSuites:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
```
### Strict SNI Checking
With strict SNI checking, Traefik won't allow connections from clients connections
that do not specify a server_name extension.
```toml tab="TOML"
[tls.options]
[tls.options.default]
sniStrict = true
```
```yaml tab="YAML"
tls:
options:
default:
sniStrict: true
spec:
clientAuth:
secretNames:
- secretCA
clientAuthType: RequireAndVerifyClientCert
```

2
docs/content/index.md
View file

@ -18,6 +18,6 @@ Developing Traefik, our main goal is to make it simple to use, and we're sure yo
-- The Traefik Maintainer Team
!!! Note
!!! info
If you're a businness running critical services behind Traefik, know that [Containous](https://containo.us), the company that sponsors Traefik's development, can provide [commercial support](https://containo.us/services/#commercial-support) and develops an [Enterprise Edition](https://containo.us/traefikee/) of Traefik.

4
docs/content/middlewares/addprefix.md
View file

@ -12,7 +12,7 @@ The AddPrefix middleware updates the URL Path of the request before forwarding i
```yaml tab="Docker"
# Prefixing with /foo
labels:
- "traefik.http.middlewares.add-foo.addprefix.prefix=/foo"
- "traefik.http.middlewares.add-foo.addprefix.prefix=/foo"
```
```yaml tab="Kubernetes"
@ -35,7 +35,7 @@ spec:
```yaml tab="Rancher"
# Prefixing with /foo
labels:
- "traefik.http.middlewares.add-foo.addprefix.prefix=/foo"
- "traefik.http.middlewares.add-foo.addprefix.prefix=/foo"
```
```toml tab="File (TOML)"

30
docs/content/middlewares/basicauth.md
View file

@ -16,7 +16,7 @@ The BasicAuth middleware is a quick way to restrict access to your services to k
# To create user:password pair, it's possible to use this command:
# echo $(htpasswd -nb user password) | sed -e s/\\$/\\$\\$/g
labels:
- "traefik.http.middlewares.test-auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
- "traefik.http.middlewares.test-auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
```
```yaml tab="Kubernetes"
@ -39,7 +39,7 @@ spec:
```yaml tab="Rancher"
# Declaring the user list
labels:
- "traefik.http.middlewares.test-auth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
- "traefik.http.middlewares.test-auth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
```
```toml tab="File (TOML)"
@ -59,8 +59,8 @@ http:
test-auth:
basicAuth:
users:
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
```
## Configuration Options
@ -77,7 +77,7 @@ Passwords must be encoded using MD5, SHA1, or BCrypt.
The `users` option is an array of authorized users. Each user will be declared using the `name:encoded-password` format.
!!! Note
!!! note ""
- If both `users` and `usersFile` are provided, the two are merged. The contents of `usersFile` have precedence over the values in `users`.
- For security reasons, the field `users` doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
@ -89,7 +89,7 @@ The `users` option is an array of authorized users. Each user will be declared u
# To create user:password pair, it's possible to use this command:
# echo $(htpasswd -nb user password) | sed -e s/\\$/\\$\\$/g
labels:
- "traefik.http.middlewares.test-auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
- "traefik.http.middlewares.test-auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
```
```yaml tab="Kubernetes"
@ -124,7 +124,7 @@ data:
```yaml tab="Rancher"
# Declaring the user list
labels:
- "traefik.http.middlewares.test-auth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
- "traefik.http.middlewares.test-auth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/,test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
```
```toml tab="File (TOML)"
@ -144,8 +144,8 @@ http:
test-auth:
basicAuth:
users:
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
```
### `usersFile`
@ -154,14 +154,14 @@ The `usersFile` option is the path to an external file that contains the authori
The file content is a list of `name:encoded-password`.
!!! Note
!!! note ""
- If both `users` and `usersFile` are provided, the two are merged. The contents of `usersFile` have precedence over the values in `users`.
- Because it does not make much sense to refer to a file path on Kubernetes, the `usersFile` field doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.basicauth.usersfile=/path/to/my/usersfile"
- "traefik.http.middlewares.test-auth.basicauth.usersfile=/path/to/my/usersfile"
```
```yaml tab="Kubernetes"
@ -224,7 +224,7 @@ You can customize the realm for the authentication with the `realm` option. The
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.basicauth.realm=MyRealm"
- "traefik.http.middlewares.test-auth.basicauth.realm=MyRealm"
```
```yaml tab="Kubernetes"
@ -268,7 +268,7 @@ You can define a header field to store the authenticated user using the `headerF
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.my-auth.basicauth.headerField=X-WebAuth-User"
- "traefik.http.middlewares.my-auth.basicauth.headerField=X-WebAuth-User"
```
```yaml tab="Kubernetes"
@ -309,7 +309,7 @@ Set the `removeHeader` option to `true` to remove the authorization header befor
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.basicauth.removeheader=true"
- "traefik.http.middlewares.test-auth.basicauth.removeheader=true"
```
```yaml tab="Kubernetes"
@ -330,7 +330,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-auth.basicauth.removeheader=true"
- "traefik.http.middlewares.test-auth.basicauth.removeheader=true"
```
```toml tab="File (TOML)"

222
docs/content/middlewares/buffering.md
View file

@ -16,7 +16,7 @@ This can help services deal with large data (multipart/form-data for example), a
```yaml tab="Docker"
# Sets the maximum request body to 2Mb
labels:
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=250000"
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
```
```yaml tab="Kubernetes"
@ -27,26 +27,26 @@ metadata:
name: limit
spec:
buffering:
maxRequestBodyBytes: 250000
maxRequestBodyBytes: 2000000
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.limit.buffering.maxRequestBodyBytes": "250000"
"traefik.http.middlewares.limit.buffering.maxRequestBodyBytes": "2000000"
}
```
```yaml tab="Rancher"
# Sets the maximum request body to 2Mb
labels:
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=250000"
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
```
```toml tab="File (TOML)"
# Sets the maximum request body to 2Mb
[http.middlewares]
[http.middlewares.limit.buffering]
maxRequestBodyBytes = 250000
maxRequestBodyBytes = 2000000
```
```yaml tab="File (YAML)"
@ -55,7 +55,7 @@ http:
middlewares:
limit:
buffering:
maxRequestBodyBytes: 250000
maxRequestBodyBytes: 2000000
```
## Configuration Options
@ -64,11 +64,91 @@ http:
With the `maxRequestBodyBytes` option, you can configure the maximum allowed body size for the request (in Bytes).
If the request exceeds the allowed size, the request is not forwarded to the service and the client gets a `413 (Request Entity Too Large) response.
If the request exceeds the allowed size, it is not forwarded to the service and the client gets a `413 (Request Entity Too Large)` response.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: limit
spec:
buffering:
maxRequestBodyBytes: 2000000
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.limit.buffering.maxRequestBodyBytes": "2000000"
}
```
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=2000000"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.limit.buffering]
maxRequestBodyBytes = 2000000
```
```yaml tab="File (YAML)"
http:
middlewares:
limit:
buffering:
maxRequestBodyBytes: 2000000
```
### `memRequestBodyBytes`
You can configure a thresold (in Bytes) from which the request will be buffered on disk instead of in memory with the `memRequestBodyBytes` option.
You can configure a threshold (in Bytes) from which the request will be buffered on disk instead of in memory with the `memRequestBodyBytes` option.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.limit.buffering.memRequestBodyBytes=2000000"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: limit
spec:
buffering:
memRequestBodyBytes: 2000000
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.limit.buffering.memRequestBodyBytes": "2000000"
}
```
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.limit.buffering.memRequestBodyBytes=2000000"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.limit.buffering]
memRequestBodyBytes = 2000000
```
```yaml tab="File (YAML)"
http:
middlewares:
limit:
buffering:
memRequestBodyBytes: 2000000
```
### `maxResponseBodyBytes`
@ -76,21 +156,137 @@ With the `maxReesponseBodyBytes` option, you can configure the maximum allowed r
If the response exceeds the allowed size, it is not forwarded to the client. The client gets a `413 (Request Entity Too Large) response` instead.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.limit.buffering.maxResponseBodyBytes=2000000"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: limit
spec:
buffering:
maxResponseBodyBytes: 2000000
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.limit.buffering.maxResponseBodyBytes": "2000000"
}
```
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.limit.buffering.maxResponseBodyBytes=2000000"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.limit.buffering]
maxResponseBodyBytes = 2000000
```
```yaml tab="File (YAML)"
http:
middlewares:
limit:
buffering:
maxResponseBodyBytes: 2000000
```
### `memResponseBodyBytes`
You can configure a thresold (in Bytes) from which the response will be buffered on disk instead of in memory with the `memResponseBodyBytes` option.
You can configure a threshold (in Bytes) from which the response will be buffered on disk instead of in memory with the `memResponseBodyBytes` option.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.limit.buffering.memResponseBodyBytes=2000000"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: limit
spec:
buffering:
memResponseBodyBytes: 2000000
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.limit.buffering.memResponseBodyBytes": "2000000"
}
```
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.limit.buffering.memResponseBodyBytes=2000000"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.limit.buffering]
memResponseBodyBytes = 2000000
```
```yaml tab="File (YAML)"
http:
middlewares:
limit:
buffering:
memResponseBodyBytes: 2000000
```
### `retryExpression`
You can have the Buffering middleware replay the request with the help of the `retryExpression` option.
!!! example "Retries once in case of a network error"
??? example "Retries once in case of a network error"
```toml
retryExpression = "IsNetworkError() && Attempts() < 2"
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.limit.buffering.retryExpression=IsNetworkError() && Attempts() < 2"
```
Available functions for the retry expression are:
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: limit
spec:
buffering:
retryExpression: "IsNetworkError() && Attempts() < 2"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.limit.buffering.retryExpression": "IsNetworkError() && Attempts() < 2"
}
```
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.limit.buffering.retryExpression=IsNetworkError() && Attempts() < 2"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.limit.buffering]
retryExpression = "IsNetworkError() && Attempts() < 2"
```
```yaml tab="File (YAML)"
http:
middlewares:
limit:
buffering:
retryExpression: "IsNetworkError() && Attempts() < 2"
```
The retry expression is defined as a logical combination of the functions below with the operators AND (`&&`) and OR (`||`). At least one function is required:
- `Attempts()` number of attempts (the first one counts)
- `ResponseCode()` response code of the service

48
docs/content/middlewares/chain.md
View file

@ -14,14 +14,14 @@ Example "A Chain for WhiteList, BasicAuth, and HTTPS"
```yaml tab="Docker"
labels:
- "traefik.http.routers.router1.service=service1"
- "traefik.http.routers.router1.middlewares=secured"
- "traefik.http.routers.router1.rule=Host(`mydomain`)"
- "traefik.http.middlewares.secured.chain.middlewares=https-only,known-ips,auth-users"
- "traefik.http.middlewares.auth-users.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "traefik.http.middlewares.https-only.redirectscheme.scheme=https"
- "traefik.http.middlewares.known-ips.ipwhitelist.sourceRange=192.168.1.7,127.0.0.1/32"
- "http.services.service1.loadbalancer.server.port=80"
- "traefik.http.routers.router1.service=service1"
- "traefik.http.routers.router1.middlewares=secured"
- "traefik.http.routers.router1.rule=Host(`mydomain`)"
- "traefik.http.middlewares.secured.chain.middlewares=https-only,known-ips,auth-users"
- "traefik.http.middlewares.auth-users.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "traefik.http.middlewares.https-only.redirectscheme.scheme=https"
- "traefik.http.middlewares.known-ips.ipwhitelist.sourceRange=192.168.1.7,127.0.0.1/32"
- "http.services.service1.loadbalancer.server.port=80"
```
```yaml tab="Kubernetes"
@ -98,14 +98,14 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.routers.router1.service=service1"
- "traefik.http.routers.router1.middlewares=secured"
- "traefik.http.routers.router1.rule=Host(`mydomain`)"
- "traefik.http.middlewares.secured.chain.middlewares=https-only,known-ips,auth-users"
- "traefik.http.middlewares.auth-users.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "traefik.http.middlewares.https-only.redirectscheme.scheme=https"
- "traefik.http.middlewares.known-ips.ipwhitelist.sourceRange=192.168.1.7,127.0.0.1/32"
- "http.services.service1.loadbalancer.server.port=80"
- "traefik.http.routers.router1.service=service1"
- "traefik.http.routers.router1.middlewares=secured"
- "traefik.http.routers.router1.rule=Host(`mydomain`)"
- "traefik.http.middlewares.secured.chain.middlewares=https-only,known-ips,auth-users"
- "traefik.http.middlewares.auth-users.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "traefik.http.middlewares.https-only.redirectscheme.scheme=https"
- "traefik.http.middlewares.known-ips.ipwhitelist.sourceRange=192.168.1.7,127.0.0.1/32"
- "http.services.service1.loadbalancer.server.port=80"
```
```toml tab="File (TOML)"
@ -143,21 +143,21 @@ http:
router1:
service: service1
middlewares:
- secured
- secured
rule: "Host(`mydomain`)"
middlewares:
secured:
chain:
middlewares:
- https-only
- known-ips
- auth-users
- https-only
- known-ips
- auth-users
auth-users:
basicAuth:
users:
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
https-only:
redirectScheme:
@ -166,12 +166,12 @@ http:
known-ips:
ipWhiteList:
sourceRange:
- "192.168.1.7"
- "127.0.0.1/32"
- "192.168.1.7"
- "127.0.0.1/32"
services:
service1:
loadBalancer:
servers:
- url: "http://127.0.0.1:80"
- url: "http://127.0.0.1:80"
```

25
docs/content/middlewares/circuitbreaker.md
View file

@ -12,21 +12,26 @@ When your system becomes unhealthy, the circuit becomes open and the requests ar
To assess if your system is healthy, the circuit breaker constantly monitors the services.
!!! Note
!!! note ""
- The CircuitBreaker only analyses what happens _after_ it is positioned in the middleware chain. What happens _before_ has no impact on its state.
- The CircuitBreaker only affects the routers that use it. Routers that don't use the CircuitBreaker won't be affected by its state.
!!! important
Each router will eventually gets its own instance of a given circuit breaker. If two different routers refer to the same circuit breaker definition, they will get one instance each. It means that one circuit breaker can be open while the other stays close: their state is not shared. This is the expected behavior, we want you to be able to define what makes a service healthy without having to declare a circuit breaker for each route.
Each router will eventually gets its own instance of a given circuit breaker.
If two different routers refer to the same circuit breaker definition, they will get one instance each.
It means that one circuit breaker can be open while the other stays closed: their state is not shared.
This is the expected behavior, we want you to be able to define what makes a service healthy without having to declare a circuit breaker for each route.
## Configuration Examples
```yaml tab="Docker"
# Latency Check
labels:
- "traefik.http.middlewares.latency-check.circuitbreaker.expression=LatencyAtQuantileMS(50.0) > 100"
- "traefik.http.middlewares.latency-check.circuitbreaker.expression=LatencyAtQuantileMS(50.0) > 100"
```
```yaml tab="Kubernetes"
@ -49,7 +54,7 @@ spec:
```yaml tab="Rancher"
# Latency Check
labels:
- "traefik.http.middlewares.latency-check.circuitbreaker.expression=LatencyAtQuantileMS(50.0) > 100"
- "traefik.http.middlewares.latency-check.circuitbreaker.expression=LatencyAtQuantileMS(50.0) > 100"
```
```toml tab="File (TOML)"
@ -117,7 +122,7 @@ The `ResponseCodeRatio` accepts four parameters, `from`, `to`, `dividedByFrom`,
The operation that will be computed is sum(`to` -> `from`) / sum (`dividedByFrom` -> `dividedByTo`).
!!! Note
!!! note ""
If sum (`dividedByFrom` -> `dividedByTo`) equals 0, then `ResponseCodeRatio` returns 0.
`from`is inclusive, `to` is exclusive.
@ -130,7 +135,7 @@ You can trigger the circuit breaker when a given proportion of your requests bec
For example, the expression `LatencyAtQuantileMS(50.0) > 100` will trigger the circuit breaker when the median latency (quantile 50) reaches 100MS.
!!! Note
!!! note ""
You must provide a float number (with the trailing .0) for the quantile value
@ -155,14 +160,16 @@ Here is the list of supported operators:
- Lesser or equal than (`<=`)
- Equal (`==`)
- Not Equal (`!=`)
### Fallback mechanism
The fallback mechanism returns a `HTTP 503 Service Unavailable` to the client (instead of calling the target service). This behavior cannot be configured.
The fallback mechanism returns a `HTTP 503 Service Unavailable` to the client (instead of calling the target service).
This behavior cannot be configured.
### `CheckPeriod`
The interval used to evaluate `expression` and decide if the state of the circuit breaker must change. By default, `CheckPeriod` is 100Ms. This value cannot be configured.
The interval used to evaluate `expression` and decide if the state of the circuit breaker must change.
By default, `CheckPeriod` is 100ms. This value cannot be configured.
### `FallbackDuration`

18
docs/content/middlewares/compress.md
View file

@ -12,7 +12,7 @@ The Compress middleware enables the gzip compression.
```yaml tab="Docker"
# Enable gzip compression
labels:
- "traefik.http.middlewares.test-compress.compress=true"
- "traefik.http.middlewares.test-compress.compress=true"
```
```yaml tab="Kubernetes"
@ -34,7 +34,7 @@ spec:
```yaml tab="Rancher"
# Enable gzip compression
labels:
- "traefik.http.middlewares.test-compress.compress=true"
- "traefik.http.middlewares.test-compress.compress=true"
```
```toml tab="File (TOML)"
@ -51,10 +51,10 @@ http:
compress: {}
```
## Notes
Responses are compressed when:
* The response body is larger than `1400` bytes.
* The `Accept-Encoding` request header contains `gzip`.
* The response is not already compressed, i.e. the `Content-Encoding` response header is not already set.
!!! info
Responses are compressed when:
* The response body is larger than `1400` bytes.
* The `Accept-Encoding` request header contains `gzip`.
* The response is not already compressed, i.e. the `Content-Encoding` response header is not already set.

26
docs/content/middlewares/digestauth.md
View file

@ -12,7 +12,7 @@ The DigestAuth middleware is a quick way to restrict access to your services to
```yaml tab="Docker"
# Declaring the user list
labels:
- "traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
- "traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
```
```yaml tab="Kubernetes"
@ -35,7 +35,7 @@ spec:
```yaml tab="Rancher"
# Declaring the user list
labels:
- "traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
- "traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
```
```toml tab="File (TOML)"
@ -55,8 +55,8 @@ http:
test-auth:
digestAuth:
users:
- "test:traefik:a2688e031edb4be6a3797f3882655c05"
- "test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
- "test:traefik:a2688e031edb4be6a3797f3882655c05"
- "test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
```
## Configuration Options
@ -69,14 +69,14 @@ http:
The `users` option is an array of authorized users. Each user will be declared using the `name:realm:encoded-password` format.
!!! Note
!!! note ""
- If both `users` and `usersFile` are provided, the two are merged. The contents of `usersFile` have precedence over the values in `users`.
- For security reasons, the field `users` doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
- "traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
```
```yaml tab="Kubernetes"
@ -108,7 +108,7 @@ data:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
- "traefik.http.middlewares.test-auth.digestauth.users=test:traefik:a2688e031edb4be6a3797f3882655c05,test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
```
```toml tab="File (TOML)"
@ -126,8 +126,8 @@ http:
test-auth:
digestAuth:
users:
- "test:traefik:a2688e031edb4be6a3797f3882655c05"
- "test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
- "test:traefik:a2688e031edb4be6a3797f3882655c05"
- "test2:traefik:518845800f9e2bfb1f1f740ec24f074e"
```
### `usersFile`
@ -136,14 +136,14 @@ The `usersFile` option is the path to an external file that contains the authori
The file content is a list of `name:realm:encoded-password`.
!!! Note
!!! note ""
- If both `users` and `usersFile` are provided, the two are merged. The contents of `usersFile` have precedence over the values in `users`.
- Because it does not make much sense to refer to a file path on Kubernetes, the `usersFile` field doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.digestauth.usersfile=/path/to/my/usersfile"
- "traefik.http.middlewares.test-auth.digestauth.usersfile=/path/to/my/usersfile"
```
```yaml tab="Kubernetes"
@ -206,7 +206,7 @@ You can customize the realm for the authentication with the `realm` option. The
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.digestauth.realm=MyRealm"
- "traefik.http.middlewares.test-auth.digestauth.realm=MyRealm"
```
```yaml tab="Kubernetes"
@ -296,7 +296,7 @@ Set the `removeHeader` option to `true` to remove the authorization header befor
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.digestauth.removeheader=true"
- "traefik.http.middlewares.test-auth.digestauth.removeheader=true"
```
```yaml tab="Kubernetes"

22
docs/content/middlewares/errorpages.md
View file

@ -15,9 +15,9 @@ The ErrorPage middleware returns a custom page in lieu of the default, according
```yaml tab="Docker"
# Dynamic Custom Error Page for 5XX Status Code
labels:
- "traefik.http.middlewares.test-errorpage.errors.status=500-599"
- "traefik.http.middlewares.test-errorpage.errors.service=serviceError"
- "traefik.http.middlewares.test-errorpage.errors.query=/{status}.html"
- "traefik.http.middlewares.test-errorpage.errors.status=500-599"
- "traefik.http.middlewares.test-errorpage.errors.service=serviceError"
- "traefik.http.middlewares.test-errorpage.errors.query=/{status}.html"
```
```yaml tab="Kubernetes"
@ -28,7 +28,7 @@ metadata:
spec:
errors:
status:
- 500-599
- 500-599
query: /{status}.html
service:
name: whoami
@ -46,9 +46,9 @@ spec:
```yaml tab="Rancher"
# Dynamic Custom Error Page for 5XX Status Code
labels:
- "traefik.http.middlewares.test-errorpage.errors.status=500-599"
- "traefik.http.middlewares.test-errorpage.errors.service=serviceError"
- "traefik.http.middlewares.test-errorpage.errors.query=/{status}.html"
- "traefik.http.middlewares.test-errorpage.errors.status=500-599"
- "traefik.http.middlewares.test-errorpage.errors.service=serviceError"
- "traefik.http.middlewares.test-errorpage.errors.query=/{status}.html"
```
```toml tab="File (TOML)"
@ -70,7 +70,7 @@ http:
test-errorpage:
errors:
status:
- "500-599"
- "500-599"
service: serviceError
query: "/{status}.html"
@ -78,7 +78,7 @@ http:
# ... definition of error-handler-service and my-service
```
!!! note
!!! note ""
In this example, the error page URL is based on the status code (`query=/{status}.html`).
## Configuration Options
@ -89,7 +89,7 @@ The `status` that will trigger the error page.
The status code ranges are inclusive (`500-599` will trigger with every code between `500` and `599`, `500` and `599` included).
!!! Note
!!! note ""
You can define either a status code like `500` or ranges with a syntax like `500-599`.
@ -97,7 +97,7 @@ The status code ranges are inclusive (`500-599` will trigger with every code bet
The service that will serve the new requested error page.
!!! Note
!!! note ""
In kubernetes, you need to reference a kubernetes service instead of a traefik service.
### `query`

71
docs/content/middlewares/forwardauth.md
View file

@ -14,7 +14,7 @@ Otherwise, the response from the authentication server is returned.
```yaml tab="Docker"
# Forward authentication to authserver.com
labels:
- "traefik.http.middlewares.test-auth.forwardauth.address=https://authserver.com/auth"
- "traefik.http.middlewares.test-auth.forwardauth.address=https://authserver.com/auth"
```
```yaml tab="Kubernetes"
@ -37,7 +37,7 @@ spec:
```yaml tab="Rancher"
# Forward authentication to authserver.com
labels:
- "traefik.http.middlewares.test-auth.forwardauth.address=https://authserver.com/auth"
- "traefik.http.middlewares.test-auth.forwardauth.address=https://authserver.com/auth"
```
```toml tab="File (TOML)"
@ -64,7 +64,7 @@ The `address` option defines the authentication server address.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.address=https://authserver.com/auth"
- "traefik.http.middlewares.test-auth.forwardauth.address=https://authserver.com/auth"
```
```yaml tab="Kubernetes"
@ -85,7 +85,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.address=https://authserver.com/auth"
- "traefik.http.middlewares.test-auth.forwardauth.address=https://authserver.com/auth"
```
```toml tab="File (TOML)"
@ -108,7 +108,7 @@ Set the `trustForwardHeader` option to `true` to trust all the existing `X-Forwa
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader=true"
- "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader=true"
```
```yaml tab="Kubernetes"
@ -130,7 +130,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader=true"
- "traefik.http.middlewares.test-auth.forwardauth.trustForwardHeader=true"
```
```toml tab="File (TOML)"
@ -155,7 +155,7 @@ The `authResponseHeaders` option is the list of the headers to copy from the aut
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=X-Auth-User, X-Secret"
- "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=X-Auth-User, X-Secret"
```
```yaml tab="Kubernetes"
@ -167,8 +167,8 @@ spec:
forwardAuth:
address: https://authserver.com/auth
authResponseHeaders:
- X-Auth-User
- X-Secret
- X-Auth-User
- X-Secret
```
```json tab="Marathon"
@ -179,7 +179,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=X-Auth-User, X-Secret"
- "traefik.http.middlewares.test-auth.forwardauth.authResponseHeaders=X-Auth-User, X-Secret"
```
```toml tab="File (TOML)"
@ -196,8 +196,8 @@ http:
forwardAuth:
address: "https://authserver.com/auth"
authResponseHeaders:
- "X-Auth-User"
- "X-Secret"
- "X-Auth-User"
- "X-Secret"
```
### `tls`
@ -206,11 +206,11 @@ The `tls` option is the TLS configuration from Traefik to the authentication ser
#### `tls.ca`
TODO add description.
Certificate Authority used for the secured connection to the authentication server.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.tls.ca=path/to/local.crt"
- "traefik.http.middlewares.test-auth.forwardauth.tls.ca=path/to/local.crt"
```
```yaml tab="Kubernetes"
@ -243,7 +243,7 @@ data:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.tls.ca=path/to/local.crt"
- "traefik.http.middlewares.test-auth.forwardauth.tls.ca=path/to/local.crt"
```
```toml tab="File (TOML)"
@ -266,11 +266,16 @@ http:
#### `tls.caOptional`
TODO add description.
Policy used for the secured connection with TLS Client Authentication to the authentication server.
Requires `tls.ca` to be defined.
- `true`: VerifyClientCertIfGiven
- `false`: RequireAndVerifyClientCert
- if `tls.ca` is undefined NoClientCert
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.tls.caOptional=true"
- "traefik.http.middlewares.test-auth.forwardauth.tls.caOptional=true"
```
```yaml tab="Kubernetes"
@ -293,7 +298,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.tls.caOptional=true"
- "traefik.http.middlewares.test-auth.forwardauth.tls.caOptional=true"
```
```toml tab="File (TOML)"
@ -316,12 +321,12 @@ http:
#### `tls.cert`
TODO add description.
Public certificate used for the secured connection to the authentication server.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"
- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"
```
```yaml tab="Kubernetes"
@ -356,8 +361,8 @@ data:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"
- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"
```
```toml tab="File (TOML)"
@ -380,17 +385,17 @@ http:
key: "path/to/foo.key"
```
!!! Note
!!! info
For security reasons, the field doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
#### `tls.key`
TODO add description.
Private certificate used for the secure connection to the authentication server.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"
- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"
```
```yaml tab="Kubernetes"
@ -425,8 +430,8 @@ data:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"
- "traefik.http.middlewares.test-auth.forwardauth.tls.cert=path/to/foo.cert"
- "traefik.http.middlewares.test-auth.forwardauth.tls.key=path/to/foo.key"
```
```toml tab="File (TOML)"
@ -449,16 +454,16 @@ http:
key: "path/to/foo.key"
```
!!! Note
!!! info
For security reasons, the field doesn't exist for Kubernetes IngressRoute, and one should use the `secret` field instead.
#### `tls.insecureSkipVerify`
TODO add description.
If `insecureSkipVerify` is `true`, TLS for the connection to authentication server accepts any certificate presented by the server and any host name in that certificate.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.tls.insecureSkipVerify=true"
- "traefik.http.middlewares.test-auth.forwardauth.tls.insecureSkipVerify=true"
```
```yaml tab="Kubernetes"
@ -480,7 +485,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-auth.forwardauth.tls.InsecureSkipVerify=true"
- "traefik.http.middlewares.test-auth.forwardauth.tls.InsecureSkipVerify=true"
```
```toml tab="File (TOML)"

16
docs/content/middlewares/headers.md
View file

@ -15,8 +15,8 @@ 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=value"
- "traefik.http.middlewares.testHeader.headers.customrequestheaders.X-Script-Name=test"
- "traefik.http.middlewares.testHeader.headers.customresponseheaders.X-Custom-Response-Header=value"
```
```yaml tab="Kubernetes"
@ -41,8 +41,8 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
- "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header=value"
- "traefik.http.middlewares.testheader.headers.customrequestheaders.X-Script-Name=test"
- "traefik.http.middlewares.testheader.headers.customresponseheaders.X-Custom-Response-Header=value"
```
```toml tab="File (TOML)"
@ -236,9 +236,9 @@ http:
testHeader:
headers:
accessControlAllowMethod:
- GET
- OPTIONS
- PUT
- GET
- OPTIONS
- PUT
accessControlAllowOrigin: "origin-list-or-null"
accessControlMaxAge: 100
addVaryHeader: true
@ -251,7 +251,7 @@ http:
!!! warning
If the custom header name is the same as one header name of the request or response, it will be replaced.
!!! note
!!! note ""
The detailed documentation for the security headers can be found in [unrolled/secure](https://github.com/unrolled/secure#available-options).
### `customRequestHeaders`

123
docs/content/middlewares/inflightreq.md
View file

@ -11,7 +11,7 @@ To proactively prevent services from being overwhelmed with high load, a limit o
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.amount=10"
- "traefik.http.middlewares.test-inflightreq.inflightreq.amount=10"
```
```yaml tab="Kubernetes"
@ -33,7 +33,7 @@ spec:
```yaml tab="Rancher"
# Limiting to 10 simultaneous connections
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.amount=10"
- "traefik.http.middlewares.test-inflightreq.inflightreq.amount=10"
```
```toml tab="File (TOML)"
@ -59,6 +59,49 @@ http:
The `amount` option defines the maximum amount of allowed simultaneous in-flight request.
The middleware will return an `HTTP 429 Too Many Requests` if there are already `amount` requests in progress (based on the same `sourceCriterion` strategy).
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.amount=10"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: test-inflightreq
spec:
inFlightReq:
amount: 10
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-inflightreq.inflightreq.amount": "10"
}
```
```yaml tab="Rancher"
# Limiting to 10 simultaneous connections
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.amount=10"
```
```toml tab="File (TOML)"
# Limiting to 10 simultaneous connections
[http.middlewares]
[http.middlewares.test-inflightreq.inFlightReq]
amount = 10
```
```yaml tab="File (YAML)"
# Limiting to 10 simultaneous connections
http:
middlewares:
test-inflightreq:
inFlightReq:
amount: 10
```
### `sourceCriterion`
SourceCriterion defines what criterion is used to group requests as originating from a common source.
@ -76,7 +119,7 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
- If `depth` is greater than the total number of IPs in `X-Forwarded-For`, then the client IP will be empty.
- `depth` is ignored if its value is lesser than or equal to 0.
!!! note "Example of Depth & X-Forwarded-For"
!!! 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`).
@ -86,14 +129,58 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
| `"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` | `""` |
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.ipstrategy.depth=2"
```
```yaml tab="Kubernetes"
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: test-inflightreq
spec:
inFlightReq:
sourceCriterion:
ipStrategy:
depth: 2
```
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.ipstrategy.depth=2"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.ipstrategy.depth": "2"
}
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-inflightreq.inflightreq]
[http.middlewares.test-inflightreq.inFlightReq.sourceCriterion.ipStrategy]
depth = 2
```
```yaml tab="File (YAML)"
http:
middlewares:
test-inflightreq:
inFlightReq:
sourceCriterion:
ipStrategy:
depth: 2
```
##### `ipStrategy.excludedIPs`
`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.
!!! important "If `depth` is specified, `excludedIPs` is ignored."
!!! note "Example of ExcludedIPs & X-Forwarded-For"
!!! example "Example of ExcludedIPs & X-Forwarded-For"
| `X-Forwarded-For` | `excludedIPs` | clientIP |
|-----------------------------------------|-----------------------|--------------|
@ -105,7 +192,7 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"
```
```yaml tab="Kubernetes"
@ -122,17 +209,17 @@ spec:
- 192.168.1.7
```
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.ipstrategy.excludedips": "127.0.0.1/32, 192.168.1.7"
}
```
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"
```
```toml tab="File (TOML)"
[http.middlewares]
[http.middlewares.test-inflightreq.inflightreq]
@ -148,8 +235,8 @@ http:
sourceCriterion:
ipStrategy:
excludedIPs:
- "127.0.0.1/32"
- "192.168.1.7"
- "127.0.0.1/32"
- "192.168.1.7"
```
#### `sourceCriterion.requestHeaderName`
@ -158,7 +245,7 @@ Requests having the same value for the given header are grouped as coming from t
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.requestheadername=username"
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.requestheadername=username"
```
```yaml tab="Kubernetes"
@ -174,7 +261,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.requestheadername=username"
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.requestheadername=username"
```
```json tab="Marathon"
@ -205,7 +292,7 @@ Whether to consider the request host as the source.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.requesthost=true"
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.requesthost=true"
```
```yaml tab="Kubernetes"
@ -221,7 +308,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.requesthost=true"
- "traefik.http.middlewares.test-inflightreq.inflightreq.sourcecriterion.requesthost=true"
```
```json tab="Marathon"

97
docs/content/middlewares/ipwhitelist.md
View file

@ -12,7 +12,7 @@ IPWhitelist accepts / refuses requests based on the client IP.
```yaml tab="Docker"
# Accepts request from defined IP
labels:
- "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
```
```yaml tab="Kubernetes"
@ -23,8 +23,8 @@ metadata:
spec:
ipWhiteList:
sourceRange:
- 127.0.0.1/32
- 192.168.1.7
- 127.0.0.1/32
- 192.168.1.7
```
```json tab="Marathon"
@ -36,7 +36,7 @@ spec:
```yaml tab="Rancher"
# Accepts request from defined IP
labels:
- "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
```
```toml tab="File (TOML)"
@ -53,8 +53,8 @@ http:
test-ipwhitelist:
ipWhiteList:
sourceRange:
- "127.0.0.1/32"
- "192.168.1.7"
- "127.0.0.1/32"
- "192.168.1.7"
```
## Configuration Options
@ -71,23 +71,13 @@ The `ipStrategy` option defines two parameters that sets how Traefik will determ
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).
!!! note "Examples of Depth & X-Forwarded-For"
!!! example "Examples 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 for the whitelisting would be `"12.0.0.1"` (`depth=2`).
??? note "More examples"
| `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` | `""` |
```yaml tab="Docker"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
labels:
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"
```
```yaml tab="Kubernetes"
@ -99,8 +89,8 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
spec:
ipWhiteList:
sourceRange:
- 127.0.0.1/32
- 192.168.1.7
- 127.0.0.1/32
- 192.168.1.7
ipStrategy:
depth: 2
```
@ -108,14 +98,14 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
```yaml tab="Rancher"
# Whitelisting Based on `X-Forwarded-For` with `depth=2`
labels:
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth=2"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange": "127.0.0.1/32, 192.168.1.7",
"traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth": "2"
"traefik.http.middlewares.testIPwhitelist.ipwhitelist.sourcerange": "127.0.0.1/32, 192.168.1.7",
"traefik.http.middlewares.testIPwhitelist.ipwhitelist.ipstrategy.depth": "2"
}
```
@ -135,34 +125,29 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
test-ipwhitelist:
ipWhiteList:
sourceRange:
- "127.0.0.1/32"
- "192.168.1.7"
- "127.0.0.1/32"
- "192.168.1.7"
ipStrategy:
depth: 2
```
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 for the whitelisting would be `"12.0.0.1"` (`depth=2`).
??? example "More examples"
| `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` | `""` |
!!! note
!!! info
- If `depth` is greater than the total number of IPs in `X-Forwarded-For`, then the client IP will be empty.
- `depth` is ignored if its value is lesser than or equal to 0.
#### `ipStrategy.excludedIPs`
`excludedIPs` tells Traefik to scan the `X-Forwarded-For` header and pick the first IP not in the list.
!!! note "Examples 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"` | `""` |
!!! important
If `depth` is specified, `excludedIPs` is ignored.
```yaml tab="Docker"
# Exclude from `X-Forwarded-For`
labels:
@ -179,19 +164,19 @@ spec:
ipWhiteList:
ipStrategy:
excludedIPs:
- 127.0.0.1/32
- 192.168.1.7
- 127.0.0.1/32
- 192.168.1.7
```
```yaml tab="Rancher"
# Exclude from `X-Forwarded-For`
labels:
- "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"
- "traefik.http.middlewares.test-ipwhitelist.ipwhitelist.ipstrategy.excludedips=127.0.0.1/32, 192.168.1.7"
```
```json tab="Marathon"
"labels": {
"traefik.http.middlewares.test-ipwhitelist.ipwhitelist.ipstrategy.excludedips": "127.0.0.1/32, 192.168.1.7"
"traefik.http.middlewares.test-ipwhitelist.ipwhitelist.ipstrategy.excludedips": "127.0.0.1/32, 192.168.1.7"
}
```
@ -211,6 +196,20 @@ http:
ipWhiteList:
ipStrategy:
excludedIPs:
- "127.0.0.1/32"
- "192.168.1.7"
- "127.0.0.1/32"
- "192.168.1.7"
```
`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 "Examples 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"` | `""` |

6
docs/content/middlewares/overview.md
View file

@ -60,7 +60,7 @@ spec:
routes:
# more fields...
middlewares:
- name: stripprefix
- name: stripprefix
```
```json tab="Marathon"
@ -106,7 +106,7 @@ http:
router1:
service: myService
middlewares:
- "foo-add-prefix"
- "foo-add-prefix"
rule: "Host(`example.com`)"
middlewares:
@ -118,7 +118,7 @@ http:
service1:
loadBalancer:
servers:
- url: "http://127.0.0.1:80"
- url: "http://127.0.0.1:80"
```
## Provider Namespace

82
docs/content/middlewares/passtlsclientcert.md
View file

@ -16,7 +16,7 @@ Pass the escaped pem in the `X-Forwarded-Tls-Client-Cert` header.
```yaml tab="Docker"
# Pass the escaped pem in the `X-Forwarded-Tls-Client-Cert` header.
labels:
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.pem=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.pem=true"
```
```yaml tab="Kubernetes"
@ -38,7 +38,7 @@ spec:
```yaml tab="Rancher"
# Pass the escaped pem in the `X-Forwarded-Tls-Client-Cert` header.
labels:
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.pem=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.pem=true"
```
```toml tab="File (TOML)"
@ -62,23 +62,23 @@ http:
```yaml tab="Docker"
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
labels:
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notafter=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notbefore=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.sans=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.commonname=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.country=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.domaincomponent=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.locality=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organization=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.province=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.serialnumber=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.commonname=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.country=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.domaincomponent=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.locality=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.organization=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.province=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.serialnumber=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notafter=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notbefore=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.sans=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.commonname=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.country=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.domaincomponent=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.locality=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organization=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.province=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.serialnumber=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.commonname=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.country=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.domaincomponent=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.locality=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.organization=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.province=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.serialnumber=true"
```
```yaml tab="Kubernetes"
@ -114,23 +114,23 @@ http:
```yaml tab="Rancher"
# Pass all the available info in the `X-Forwarded-Tls-Client-Cert-Info` header
labels:
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notafter=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notbefore=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.sans=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.commonname=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.country=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.domaincomponent=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.locality=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organization=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.province=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.serialnumber=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.commonname=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.country=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.domaincomponent=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.locality=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.organization=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.province=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.serialnumber=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notafter=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.notbefore=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.sans=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.commonname=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.country=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.domaincomponent=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.locality=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.organization=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.province=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.subject.serialnumber=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.commonname=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.country=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.domaincomponent=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.locality=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.organization=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.province=true"
- "traefik.http.middlewares.test-passtlsclientcert.passtlsclientcert.info.issuer.serialnumber=true"
```
```json tab="Marathon"
@ -218,7 +218,7 @@ PassTLSClientCert can add two headers to the request:
- `X-Forwarded-Tls-Client-Cert` that contains the escaped pem.
- `X-Forwarded-Tls-Client-Cert-Info` that contains all the selected certificate information in an escaped string.
!!! note
!!! info
The headers are filled with escaped string so it can be safely placed inside a URL query.
In the following example, you can see a complete certificate. We will use each part of it to explain the middleware options.
@ -374,12 +374,12 @@ In the example, it is the part between `-----BEGIN CERTIFICATE-----` and `-----E
-----END CERTIFICATE-----
```
!!! note "Extracted data"
!!! info "Extracted data"
The delimiters and `\n` will be removed.
If there are more than one certificate, they are separated by a "`;`".
!!! note "`X-Forwarded-Tls-Client-Cert` value could exceed the web server header size limit"
!!! warning "`X-Forwarded-Tls-Client-Cert` value could exceed the web server header size limit"
The header size limit of web servers is commonly between 4kb and 8kb.
You could change the server configuration to allow bigger header or use the `info` option with the needed field(s).
@ -395,7 +395,7 @@ The following example shows an unescaped result that uses all the available fiel
Subject="DC=org,DC=cheese,C=FR,C=US,ST=Cheese org state,ST=Cheese com state,L=TOULOUSE,L=LYON,O=Cheese,O=Cheese 2,CN=*.cheese.com",Issuer="DC=org,DC=cheese,C=FR,C=US,ST=Signing State,ST=Signing State 2,L=TOULOUSE,L=LYON,O=Cheese,O=Cheese 2,CN=Simple Signing CA 2",NB=1544094616,NA=1607166616,SAN=*.cheese.org,*.cheese.net,*.cheese.com,test@cheese.org,test@cheese.net,10.0.1.0,10.0.1.2
```
!!! note "Multiple certificates"
!!! info "Multiple certificates"
If there are more than one certificate, they are separated by a `;`.
@ -450,7 +450,7 @@ The escape SANs info part will be like:
SAN=*.cheese.org,*.cheese.net,*.cheese.com,test@cheese.org,test@cheese.net,10.0.1.0,10.0.1.2
```
!!! note "multiple values"
!!! info "multiple values"
All the SANs data are separated by a `,`.

65
docs/content/middlewares/ratelimit.md
View file

@ -11,8 +11,8 @@ The RateLimit middleware ensures that services will receive a _fair_ number of r
# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 50 requests is allowed.
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=50"
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=50"
```
```yaml tab="Kubernetes"
@ -39,8 +39,8 @@ spec:
# Here, an average of 100 requests per second is allowed.
# In addition, a burst of 50 requests is allowed.
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=50"
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=50"
```
```toml tab="File (TOML)"
@ -72,7 +72,7 @@ It defaults to 0, which means no rate limiting.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
```
```yaml tab="Kubernetes"
@ -93,7 +93,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.average=100"
```
```toml tab="File (TOML)"
@ -117,7 +117,7 @@ It defaults to 1.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"
```
```yaml tab="Kubernetes"
@ -138,7 +138,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"
- "traefik.http.middlewares.test-ratelimit.ratelimit.burst=100"
```
@ -173,7 +173,7 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
- If `depth` is greater than the total number of IPs in `X-Forwarded-For`, then the client IP will be empty.
- `depth` is ignored if its value is lesser than or equal to 0.
!!! note "Example of Depth & X-Forwarded-For"
!!! 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`).
@ -185,24 +185,9 @@ The `depth` option tells Traefik to use the `X-Forwarded-For` header and take th
##### `ipStrategy.excludedIPs`
`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.
!!! note "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"` | `""` |
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-ratelimit.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"
```
```yaml tab="Kubernetes"
@ -221,7 +206,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-ratelimit.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"
```
```json tab="Marathon"
@ -245,17 +230,31 @@ http:
sourceCriterion:
ipStrategy:
excludedIPs:
- "127.0.0.1/32"
- "192.168.1.7"
- "127.0.0.1/32"
- "192.168.1.7"
```
`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:
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requestheadername=username"
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requestheadername=username"
```
```yaml tab="Kubernetes"
@ -271,7 +270,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requestheadername=username"
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requestheadername=username"
```
```json tab="Marathon"
@ -302,7 +301,7 @@ Whether to consider the request host as the source.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requesthost=true"
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requesthost=true"
```
```yaml tab="Kubernetes"
@ -318,7 +317,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requesthost=true"
- "traefik.http.middlewares.test-ratelimit.ratelimit.sourcecriterion.requesthost=true"
```
```json tab="Marathon"
@ -341,4 +340,4 @@ http:
rateLimit:
sourceCriterion:
requestHost: true
```
```

9
docs/content/middlewares/redirectregex.md
View file

@ -15,8 +15,8 @@ RegexRedirect redirect a request from an url to another with regex matching and
# Redirect with domain replacement
# Note: all dollar signs need to be doubled for escaping.
labels:
- "traefik.http.middlewares.test-redirectregex.redirectregex.regex=^http://localhost/(.*)"
- "traefik.http.middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/$${1}"
- "traefik.http.middlewares.test-redirectregex.redirectregex.regex=^http://localhost/(.*)"
- "traefik.http.middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/$${1}"
```
```yaml tab="Kubernetes"
@ -42,8 +42,8 @@ spec:
# Redirect with domain replacement
# Note: all dollar signs need to be doubled for escaping.
labels:
- "traefik.http.middlewares.test-redirectregex.redirectregex.regex=^http://localhost/(.*)"
- "traefik.http.middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/$${1}"
- "traefik.http.middlewares.test-redirectregex.redirectregex.regex=^http://localhost/(.*)"
- "traefik.http.middlewares.test-redirectregex.redirectregex.replacement=http://mydomain/$${1}"
```
```toml tab="File (TOML)"
@ -85,4 +85,3 @@ The `regex` option is the regular expression to match and capture elements from
### `replacement`
The `replacement` option defines how to modify the URL to have the new target URL.

4
docs/content/middlewares/redirectscheme.md
View file

@ -14,7 +14,7 @@ RegexRedirect redirect request from a scheme to another.
```yaml tab="Docker"
# Redirect to https
labels:
- "traefik.http.middlewares.test-redirectscheme.redirectscheme.scheme=https"
- "traefik.http.middlewares.test-redirectscheme.redirectscheme.scheme=https"
```
```yaml tab="Kubernetes"
@ -37,7 +37,7 @@ spec:
```yaml tab="Rancher"
# Redirect to https
labels:
- "traefik.http.middlewares.test-redirectscheme.redirectscheme.scheme=https"
- "traefik.http.middlewares.test-redirectscheme.redirectscheme.scheme=https"
```
```toml tab="File (TOML)"

4
docs/content/middlewares/replacepath.md
View file

@ -14,7 +14,7 @@ Replace the path of the request url.
```yaml tab="Docker"
# Replace the path by /foo
labels:
- "traefik.http.middlewares.test-replacepath.replacepath.path=/foo"
- "traefik.http.middlewares.test-replacepath.replacepath.path=/foo"
```
```yaml tab="Kubernetes"
@ -37,7 +37,7 @@ spec:
```yaml tab="Rancher"
# Replace the path by /foo
labels:
- "traefik.http.middlewares.test-replacepath.replacepath.path=/foo"
- "traefik.http.middlewares.test-replacepath.replacepath.path=/foo"
```
```toml tab="File (TOML)"

8
docs/content/middlewares/replacepathregex.md
View file

@ -14,8 +14,8 @@ The ReplaceRegex replace a path from an url to another with regex matching and r
```yaml tab="Docker"
# Replace path with regex
labels:
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.regex=^/foo/(.*)"
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.replacement=/bar/$1"
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.regex=^/foo/(.*)"
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.replacement=/bar/$1"
```
```yaml tab="Kubernetes"
@ -40,8 +40,8 @@ spec:
```yaml tab="Rancher"
# Replace path with regex
labels:
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.regex=^/foo/(.*)"
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.replacement=/bar/$1"
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.regex=^/foo/(.*)"
- "traefik.http.middlewares.test-replacepathregex.replacepathregex.replacement=/bar/$1"
```
```toml tab="File (TOML)"

6
docs/content/middlewares/retry.md
View file

@ -15,7 +15,7 @@ To be clear, as soon as the server answers, the middleware stops retrying, regar
```yaml tab="Docker"
# Retry to send request 4 times
labels:
- "traefik.http.middlewares.test-retry.retry.attempts=4"
- "traefik.http.middlewares.test-retry.retry.attempts=4"
```
```yaml tab="Kubernetes"
@ -38,7 +38,7 @@ spec:
```yaml tab="Rancher"
# Retry to send request 4 times
labels:
- "traefik.http.middlewares.test-retry.retry.attempts=4"
- "traefik.http.middlewares.test-retry.retry.attempts=4"
```
```toml tab="File (TOML)"
@ -63,4 +63,4 @@ http:
_mandatory_
The `attempts` option defines how many times the request should be retried.
The `attempts` option defines how many times the request should be retried.

12
docs/content/middlewares/stripprefix.md
View file

@ -14,7 +14,7 @@ Remove the specified prefixes from the URL path.
```yaml tab="Docker"
# Strip prefix /foobar and /fiibar
labels:
- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar"
- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar"
```
```yaml tab="Kubernetes"
@ -26,8 +26,8 @@ metadata:
spec:
stripPrefix:
prefixes:
- /foobar
- /fiibar
- /foobar
- /fiibar
```
```json tab="Marathon"
@ -39,7 +39,7 @@ spec:
```yaml tab="Rancher"
# Strip prefix /foobar and /fiibar
labels:
- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar"
- "traefik.http.middlewares.test-stripprefix.stripprefix.prefixes=/foobar,/fiibar"
```
```toml tab="File (TOML)"
@ -56,8 +56,8 @@ http:
test-stripprefix:
stripPrefix:
prefixes:
- "/foobar"
- "/fiibar"
- "/foobar"
- "/fiibar"
```
## Configuration Options

8
docs/content/middlewares/stripprefixregex.md
View file

@ -9,7 +9,7 @@ Remove the matching prefixes from the URL path.
```yaml tab="Docker"
labels:
- "traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=/foo/[a-z0-9]+/[0-9]+/"
- "traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=/foo/[a-z0-9]+/[0-9]+/"
```
```yaml tab="Kubernetes"
@ -20,7 +20,7 @@ metadata:
spec:
stripPrefixRegex:
regex:
- "/foo/[a-z0-9]+/[0-9]+/"
- "/foo/[a-z0-9]+/[0-9]+/"
```
```json tab="Marathon"
@ -31,7 +31,7 @@ spec:
```yaml tab="Rancher"
labels:
- "traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=/foo/[a-z0-9]+/[0-9]+/"
- "traefik.http.middlewares.test-stripprefixregex.stripprefixregex.regex=/foo/[a-z0-9]+/[0-9]+/"
```
```toml tab="File (TOML)"
@ -46,7 +46,7 @@ http:
test-stripprefixregex:
stripPrefixRegex:
regex:
- "/foo/[a-z0-9]+/[0-9]+/"
- "/foo/[a-z0-9]+/[0-9]+/"
```
## Configuration Options

706
docs/content/migration/v1-to-v2.md
View file

@ -8,7 +8,7 @@ which require one to update their configuration when they migrate from v1 to v2.
The goal of this page is to recapitulate all of these changes, and in particular to give examples,
feature by feature, of how the configuration looked like in v1, and how it now looks like in v2.
!!! Note "Migration Helper"
!!! info "Migration Helper"
We created a tool to help during the migration: [traefik-migration-tool](https://github.com/containous/traefik-migration-tool)
@ -16,11 +16,12 @@ feature by feature, of how the configuration looked like in v1, and how it now l
- convert `Ingress` to Traefik `IngressRoute` resources.
- convert `acme.json` file from v1 to v2 format.
- migrate the static configuration contained in the file `traefik.toml` to a Traefik v2 file.
## Frontends and Backends Are Dead... <br/>... Long Live Routers, Middlewares, and Services
During the transition from v1 to v2, a number of internal pieces and components of Traefik were rewritten and reorganized.
As such, the combination of core notions such as frontends and backends has been replaced with the combination of routers, services, and middlewares.
As such, the combination of core notions such as frontends and backends has been replaced with the combination of [routers](../routing/routers/index.md), [services](../routing/services/index.md), and [middlewares](../middlewares/overview.md).
Typically, a router replaces a frontend, and a service assumes the role of a backend, with each router referring to a service.
However, even though a backend was in charge of applying any desired modification on the fly to the incoming request,
@ -30,7 +31,7 @@ Then any router can refer to an instance of the wanted middleware.
!!! example "One frontend with basic auth and one backend, become one router, one service, and one basic auth middleware."
### v1
!!! info "v1"
```yaml tab="Docker"
labels:
@ -92,7 +93,7 @@ Then any router can refer to an instance of the wanted middleware.
method = "wrr"
```
### v2
!!! info "v2"
```yaml tab="Docker"
labels:
@ -166,32 +167,32 @@ Then any router can refer to an instance of the wanted middleware.
rule: "Host(`test.localhost`) && PathPrefix(`/test`)"
service: my-service
middlewares:
- auth
- auth
services:
my-service:
loadBalancer:
servers:
- url: http://10.10.10.1:80
- url: http://10.10.10.2:80
- url: http://10.10.10.1:80
- url: http://10.10.10.2:80
middlewares:
auth:
basicAuth:
users:
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
```
## TLS configuration is now dynamic, per router.
TLS parameters used to be specified in the static configuration, as an entryPoint field.
With Traefik v2, a new dynamic TLS section at the root contains all the desired TLS configurations.
Then, a router's TLS field can refer to one of the TLS configurations defined at the root, hence defining the TLS configuration for that router.
Then, a [router's TLS field](../routing/routers/index.md#tls) can refer to one of the [TLS configurations](../https/tls.md) defined at the root, hence defining the [TLS configuration](../https/tls.md) for that router.
!!! example "TLS on web-secure entryPoint becomes TLS option on Router-1"
### v1
!!! info "v1"
```toml tab="File (TOML)"
# static configuration
@ -214,7 +215,7 @@ Then, a router's TLS field can refer to one of the TLS configurations defined at
--entryPoints='Name:web-secure Address::443 TLS:path/to/my.cert,path/to/my.key TLS.MinVersion:VersionTLS12 TLS.CipherSuites:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA384'
```
### v2
!!! info "v2"
```toml tab="File (TOML)"
# dynamic configuration
@ -260,8 +261,8 @@ Then, a router's TLS field can refer to one of the TLS configurations defined at
myTLSOptions:
minVersion: VersionTLS13
cipherSuites:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
```
```yaml tab="K8s IngressRoute"
@ -289,11 +290,11 @@ Then, a router's TLS field can refer to one of the TLS configurations defined at
entryPoints:
- web
routes:
- match: Host(`bar.com`)
kind: Rule
services:
- name: whoami
port: 80
- match: Host(`bar.com`)
kind: Rule
services:
- name: whoami
port: 80
tls:
options:
name: mytlsoption
@ -307,47 +308,664 @@ Then, a router's TLS field can refer to one of the TLS configurations defined at
- "traefik.http.routers.router0.tls.options=myTLSOptions@file"
```
## HTTP -> HTTPS Redirection
## HTTP to HTTPS Redirection is now configured on Routers
TODO
Previously on Traefik v1, the redirection was applied on an entry point or on a frontend.
With Traefik v2 it is applied on a [Router](../routing/routers/index.md).
## ACME (let's encrypt)
To apply a redirection, one of the redirect middlewares, [RedirectRegex](../middlewares/redirectregex.md) or [RedirectScheme](../middlewares/redirectscheme.md), has to be configured and added to the router middlewares list.
TODO
!!! example "HTTP to HTTPS redirection"
!!! info "v1"
```toml tab="File (TOML)"
# static configuration
defaultEntryPoints = ["http", "https"]
[entryPoints]
[entryPoints.http]
address = ":80"
[entryPoints.http.redirect]
entryPoint = "https"
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
[[entryPoints.https.tls.certificates]]
certFile = "examples/traefik.crt"
keyFile = "examples/traefik.key"
```
```bash tab="CLI"
--entrypoints=Name:web Address::80 Redirect.EntryPoint:web-secure
--entryPoints='Name:web-secure Address::443 TLS:path/to/my.cert,path/to/my.key'
```
!!! info "v2"
```yaml tab="Docker"
labels:
- traefik.http.routers.web.rule=Host(`foo.com`)
- traefik.http.routers.web.entrypoints=web
- traefik.http.routers.web.middlewares=redirect@file
- traefik.http.routers.web-secured.rule=Host(`foo.com`)
- traefik.http.routers.web-secured.entrypoints=web-secure
- traefik.http.routers.web-secured.tls=true
```
```yaml tab="K8s IngressRoute"
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: http-redirect-ingressRoute
spec:
entryPoints:
- web
routes:
- match: Host(`foo.com`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: redirect
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: https-ingressRoute
spec:
entryPoints:
- web-secure
routes:
- match: Host(`foo`)
kind: Rule
services:
- name: whoami
port: 80
tls: {}
---
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: redirect
spec:
redirectScheme:
scheme: https
```
```toml tab="File (TOML)"
## static configuration
# traefik.toml
[entryPoints.web]
address = ":80"
[entryPoints.web-secure]
address = ":443"
##---------------------##
## dynamic configuration
# dymanic-conf.toml
[http.routers]
[http.routers.router0]
rule = "Host(`foo.com`)"
service = "my-service"
entrypoints = ["web"]
middlewares = ["redirect"]
[http.routers.router1]
rule = "Host(`foo.com`)"
service = "my-service"
entrypoints = ["web-secure"]
[http.routers.router1.tls]
[http.services]
[[http.services.my-service.loadBalancer.servers]]
url = "http://10.10.10.1:80"
[[http.services.my-service.loadBalancer.servers]]
url = "http://10.10.10.2:80"
[http.middlewares]
[http.middlewares.redirect.redirectScheme]
scheme = "https"
[[tls.certificates]]
certFile = "/path/to/domain.cert"
keyFile = "/path/to/domain.key"
```
```yaml tab="File (YAML)"
## static configuration
# traefik.yml
entryPoints:
web:
address: ":80"
web-secure:
address: ":443"
##---------------------##
## dynamic configuration
# dymanic-conf.yml
http:
routers:
router0:
rule: "Host(`foo.com`)"
entryPoints:
- web
middlewares:
- redirect
service: my-service
router1:
rule: "Host(`foo.com`)"
entryPoints:
- web-secure
service: my-service
tls: {}
services:
my-service:
loadBalancer:
servers:
- url: http://10.10.10.1:80
- url: http://10.10.10.2:80
middlewares:
redirect:
redirectScheme:
scheme: https
tls:
certificates:
- certFile: /app/certs/server/server.pem
keyFile: /app/certs/server/server.pem
```
## ACME (LetsEncrypt)
[ACME](../https/acme.md) is now a certificate resolver (under a certificatesResolvers section) but remains in the static configuration.
!!! example "ACME from provider to a specific Certificate Resolver"
!!! info "v1"
```toml tab="File (TOML)"
# static configuration
defaultEntryPoints = ["web-secure","web"]
[entryPoints.web]
address = ":80"
[entryPoints.web.redirect]
entryPoint = "webs"
[entryPoints.web-secure]
address = ":443"
[entryPoints.https.tls]
[acme]
email = "your-email-here@my-awesome-app.org"
storage = "acme.json"
entryPoint = "web-secure"
onHostRule = true
[acme.httpChallenge]
entryPoint = "web"
```
```bash tab="CLI"
--defaultentrypoints=web-secure,web
--entryPoints=Name:web Address::80 Redirect.EntryPoint:web-secure
--entryPoints=Name:web-secure Address::443 TLS
--acme.email=your-email-here@my-awesome-app.org
--acme.storage=acme.json
--acme.entryPoint=web-secure
--acme.onHostRule=true
--acme.httpchallenge.entrypoint=http
```
!!! info "v2"
```toml tab="File (TOML)"
# static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web-secure]
address = ":443"
[certificatesResolvers.sample.acme]
email = "your-email@your-domain.org"
storage = "acme.json"
[certificatesResolvers.sample.acme.httpChallenge]
# used during the challenge
entryPoint = "web"
```
```yaml tab="File (YAML)"
entryPoints:
web:
address: ":80"
web-secure:
address: ":443"
certificatesResolvers:
sample:
acme:
email: your-email@your-domain.org
storage: acme.json
httpChallenge:
# used during the challenge
entryPoint: web
```
```bash tab="CLI"
--entryPoints.web.address=":80"
--entryPoints.websecure.address=":443"
--certificatesResolvers.sample.acme.email: your-email@your-domain.org
--certificatesResolvers.sample.acme.storage: acme.json
--certificatesResolvers.sample.acme.httpChallenge.entryPoint: web
```
## Traefik Logs
TODO
In the v2, all the [log configuration](../observability/logs.md) remains in the static part but are unified under a `log` section.
There is no more log configuration at the root level.
!!! example "Simple log configuration"
!!! info "v1"
```toml tab="File (TOML)"
# static configuration
logLevel = "DEBUG"
[traefikLog]
filePath = "/path/to/traefik.log"
format = "json"
```
```bash tab="CLI"
--logLevel="DEBUG"
--traefikLog.filePath="/path/to/traefik.log"
--traefikLog.format="json"
```
!!! info "v2"
```toml tab="File (TOML)"
# static configuration
[log]
level = "DEBUG"
filePath = "/path/to/log-file.log"
format = "json"
```
```yaml tab="File (YAML)"
# static configuration
log:
level: DEBUG
filePath: /path/to/log-file.log
format: json
```
```bash tab="CLI"
--log.level="DEBUG"
--log.filePath="/path/to/traefik.log"
--log.format="json"
```
## Tracing
TODO
Traefik v2 retains OpenTracing support. The `backend` root option from the v1 is gone, you just have to set your [tracing configuration](../observability/tracing/overview.md).
!!! example "Simple Jaeger tracing configuration"
!!! info "v1"
```toml tab="File (TOML)"
# static configuration
[tracing]
backend = "jaeger"
servicename = "tracing"
[tracing.jaeger]
samplingParam = 1.0
samplingServerURL = "http://12.0.0.1:5778/sampling"
samplingType = "const"
localAgentHostPort = "12.0.0.1:6831"
```
```bash tab="CLI"
--tracing.backend="jaeger"
--tracing.servicename="tracing"
--tracing.jaeger.localagenthostport="12.0.0.1:6831"
--tracing.jaeger.samplingparam="1.0"
--tracing.jaeger.samplingserverurl="http://12.0.0.1:5778/sampling"
--tracing.jaeger.samplingtype="const"
```
!!! info "v2"
```toml tab="File (TOML)"
# static configuration
[tracing]
servicename = "tracing"
[tracing.jaeger]
samplingParam = 1.0
samplingServerURL = "http://12.0.0.1:5778/sampling"
samplingType = "const"
localAgentHostPort = "12.0.0.1:6831"
```
```yaml tab="File (YAML)"
# static configuration
tracing:
servicename: tracing
jaeger:
samplingParam: 1
samplingServerURL: 'http://12.0.0.1:5778/sampling'
samplingType: const
localAgentHostPort: '12.0.0.1:6831'
```
```bash tab="CLI"
--tracing.servicename="tracing"
--tracing.jaeger.localagenthostport="12.0.0.1:6831"
--tracing.jaeger.samplingparam="1.0"
--tracing.jaeger.samplingserverurl="http://12.0.0.1:5778/sampling"
--tracing.jaeger.samplingtype="const"
```
## Metrics
TODO
The v2 retains metrics tools and allows metrics to be configured for the entrypoints and/or services.
For a basic configuration, the [metrics configuration](../observability/metrics/overview.md) remains the same.
!!! example "Simple Prometheus metrics configuration"
!!! info "v1"
```toml tab="File (TOML)"
# static configuration
[metrics.prometheus]
buckets = [0.1,0.3,1.2,5.0]
entryPoint = "traefik"
```
```bash tab="CLI"
--metrics.prometheus.buckets=[0.1,0.3,1.2,5.0]
--metrics.prometheus.entrypoint="traefik"
```
!!! info "v2"
```toml tab="File (TOML)"
# static configuration
[metrics.prometheus]
buckets = [0.1,0.3,1.2,5.0]
entryPoint = "metrics"
```
```yaml tab="File (YAML)"
# static configuration
metrics:
prometheus:
buckets:
- 0.1
- 0.3
- 1.2
- 5
entryPoint: metrics
```
```bash tab="CLI"
--metrics.prometheus.buckets=[0.1,0.3,1.2,5.0]
--metrics.prometheus.entrypoint="metrics"
```
## No more root level key/values
TODO
To avoid any source of confusion, there are no more configuration at the root level.
Each root item has been moved to a related section or removed.
!!! example "From root to dedicated section"
!!! info "v1"
```toml tab="File (TOML)"
# static configuration
checkNewVersion = false
sendAnonymousUsage = true
logLevel = "DEBUG"
insecureSkipVerify = true
rootCAs = [ "/mycert.cert" ]
maxIdleConnsPerHost = 200
providersThrottleDuration = "2s"
AllowMinWeightZero = true
debug = true
defaultEntryPoints = ["web", "web-secure"]
keepTrailingSlash = false
```
```bash tab="CLI"
--checknewversion=false
--sendanonymoususage=true
--loglevel="DEBUG"
--insecureskipverify=true
--rootcas="/mycert.cert"
--maxidleconnsperhost=200
--providersthrottleduration="2s"
--allowminweightzero=true
--debug=true
--defaultentrypoints="web","web-secure"
--keeptrailingslash=true
```
!!! info "v2"
```toml tab="File (TOML)"
# static configuration
[global]
checkNewVersion = true
sendAnonymousUsage = true
[log]
level = "DEBUG"
[serversTransport]
insecureSkipVerify = true
rootCAs = [ "/mycert.cert" ]
maxIdleConnsPerHost = 42
[providers]
providersThrottleDuration = 42
```
```yaml tab="File (YAML)"
# static configuration
global:
checkNewVersion: true
sendAnonymousUsage: true
log:
level: DEBUG
serversTransport:
insecureSkipVerify: true
rootCAs:
- /mycert.cert
maxIdleConnsPerHost: 42
providers:
providersThrottleDuration: 42
```
```bash tab="CLI"
--global.checknewversion=true
--global.sendanonymoususage=true
--log.level="DEBUG"
--serverstransport.insecureskipverify=true
--serverstransport.rootcas="/mycert.cert"
--serverstransport.maxidleconnsperhost=42
--providers.providersthrottleduration=42
```
## Dashboard
You need to activate the [API](../operations/dashboard.md#enabling-the-dashboard) to access the dashboard.
As the dashboard access is now secured by default you can either:
* define a [specific router](../operations/api.md#configuration) with the `api@internal` service and one authentication middleware like the following example
* or use the [unsecure](../operations/api.md#insecure) option of the API
!!! info "Dashboard with k8s and dedicated router"
As `api@internal` is not a Kubernetes service, you have to use the file provider or the `insecure` API option.
!!! example "Activate and access the dashboard"
!!! info "v1"
```toml tab="File (TOML)"
## static configuration
# traefik.toml
[entryPoints.web-secure]
address = ":443"
[entryPoints.web-secure.tls]
[entryPoints.web-secure.auth]
[entryPoints.web-secure.auth.basic]
users = [
"test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
]
[api]
entryPoint = "web-secure"
```
```bash tab="CLI"
--entryPoints='Name:web-secure Address::443 TLS Auth.Basic.Users:test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/'
--api
```
!!! info "v2"
```yaml tab="Docker"
# dynamic configuration
labels:
- "traefik.http.routers.api.rule=Host(`traefik.docker.localhost`)"
- "traefik.http.routers.api.entrypoints=web-secured"
- "traefik.http.routers.api.service=api@internal"
- "traefik.http.routers.api.middlewares=myAuth"
- "traefik.http.routers.api.tls"
- "traefik.http.middlewares.myAuth.basicauth.users=test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
```
```toml tab="File (TOML)"
## static configuration
# traefik.toml
[entryPoints.web-secure]
address = ":443"
[api]
[providers.file]
filename = "/dymanic-conf.toml"
##---------------------##
## dynamic configuration
# dymanic-conf.toml
[http.routers.api]
rule = "Host(`traefik.docker.localhost`)"
entrypoints = ["web-secure"]
service = "api@internal"
middlewares = ["myAuth"]
[http.routers.api.tls]
[http.middlewares.myAuth.basicAuth]
users = [
"test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
]
```
```yaml tab="File (YAML)"
## static configuration
# traefik.yaml
entryPoints:
web-secure:
address: ':443'
api: {}
providers:
file:
filename: /dymanic-conf.yaml
##---------------------##
## dynamic configuration
# dymanic-conf.yaml
http:
routers:
api:
rule: Host(`traefik.docker.localhost`)
entrypoints:
- web-secure
service: api@internal
middlewares:
- myAuth
tls: {}
middlewares:
myAuth:
basicAuth:
users:
- 'test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/'
```
## Providers
Supported providers, for now:
Supported [providers](../providers/overview.md), for now:
- [ ] Azure Service Fabric
- [ ] BoltDB
- [ ] Consul
- [ ] Consul Catalog
- [x] Docker
- [ ] DynamoDB
- [ ] ECS
- [ ] Etcd
- [ ] Eureka
- [x] File
- [x] Kubernetes Ingress (without annotations)
- [x] Kubernetes IngressRoute
- [x] Marathon
- [ ] Mesos
- [x] Rest
- [ ] Zookeeper
* [ ] Azure Service Fabric
* [ ] BoltDB
* [ ] Consul
* [ ] Consul Catalog
* [x] Docker
* [ ] DynamoDB
* [ ] ECS
* [ ] Etcd
* [ ] Eureka
* [x] File
* [x] Kubernetes Ingress (without annotations)
* [x] Kubernetes IngressRoute
* [x] Marathon
* [ ] Mesos
* [x] Rancher
* [x] Rest
* [ ] Zookeeper
## Some Tips You Should Known
* Different sources of static configuration (file, CLI flags, ...) cannot be [mixed](../getting-started/configuration-overview.md#the-static-configuration).
* Now, configuration elements can be referenced between different providers by using the provider namespace notation: `@<provider>`.
For instance, a router named `myrouter` in a File Provider can refer to a service named `myservice` defined in Docker Provider with the following notation: `myservice@docker`.
* Middlewares are applied in the same order as their declaration in router.
* If you have any questions feel free to join our [community forum](https://community.containo.us).

10
docs/content/observability/access-logs.md
View file

@ -32,7 +32,7 @@ By default, logs are written using the Common Log Format (CLF).
To write logs in JSON, use `json` in the `format` option.
If the given format is unsupported, the default (CLF) is used instead.
!!! note "Common Log Format"
!!! info "Common Log Format"
```html
<remote_IP_address> - <client_user_name_if_available> [<timestamp>] "<request_method> <request_path> <request_protocol>" <origin_server_HTTP_status> <origin_server_content_size> "<request_referrer>" "<request_user_agent>" <number_of_requests_received_since_Traefik_started> "<Traefik_frontend_name>" "<Traefik_backend_URL>" <request_duration_in_ms>ms
@ -95,8 +95,8 @@ accessLog:
format: json
filters:
statusCodes:
- "200"
- "300-302"
- "200"
- "300-302"
retryAttempts: true
minDuration: "10ms"
```
@ -174,7 +174,7 @@ accessLog:
--accesslog.fields.headers.names.Content-Type="keep"
```
??? list "Available Fields"
??? info "Available Fields"
| Field | Description |
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@ -214,5 +214,5 @@ accessLog:
Traefik will close and reopen its log files, assuming they're configured, on receipt of a USR1 signal.
This allows the logs to be rotated and processed by an external program, such as `logrotate`.
!!! note
!!! warning
This does not work on Windows due to the lack of USR signals.

2
docs/content/observability/logs.md
View file

@ -80,5 +80,5 @@ log:
Traefik will close and reopen its log files, assuming they're configured, on receipt of a USR1 signal.
This allows the logs to be rotated and processed by an external program, such as `logrotate`.
!!! note
!!! warning
This does not work on Windows due to the lack of USR signals.

8
docs/content/observability/metrics/prometheus.md
View file

@ -32,10 +32,10 @@ Buckets for latency metrics.
metrics:
prometheus:
buckets:
- 0.1
- 0.3
- 1.2
- 5.0
- 0.1
- 0.3
- 1.2
- 5.0
```
```bash tab="CLI"

25
docs/content/operations/api.md
View file

@ -21,7 +21,7 @@ would be to apply the following protection mechanisms:
## Configuration
If you enable the API, a new special `service` named `api@internal` is created and then can be reference in a router.
If you enable the API, a new special `service` named `api@internal` is created and can then be referenced in a router.
To enable the API handler:
@ -37,9 +37,10 @@ api: {}
--api=true
```
And then you will able to reference it like this.
And then you will be able to reference it like this:
```yaml tab="Docker"
labels:
- "traefik.http.routers.api.rule=PathPrefix(`/api`) || PathPrefix(`/dashboard`)"
- "traefik.http.routers.api.service=api@internal"
- "traefik.http.routers.api.middlewares=auth"
@ -59,9 +60,9 @@ And then you will able to reference it like this.
# Declaring the user list
labels:
- "traefik.http.routers.api.rule=PathPrefix(`/api`) || PathPrefix(`/dashboard`)"
- "traefik.http.routers.api.service=api@internal"
- "traefik.http.routers.api.middlewares=auth"
- "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
- "traefik.http.routers.api.service=api@internal"
- "traefik.http.routers.api.middlewares=auth"
- "traefik.http.middlewares.auth.basicauth.users=test:$$apr1$$H6uskkkW$$IgXLP6ewTrSuBkTrqE8wj/,test2:$$apr1$$d9hr9HBB$$4HxwgUir3HP4EsggP/QNo0"
```
```toml tab="File (TOML)"
@ -72,9 +73,9 @@ labels:
[http.middlewares.auth.basicAuth]
users = [
"test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
"test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
]
"test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
"test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0",
]
```
```yaml tab="File (YAML)"
@ -89,15 +90,15 @@ http:
auth:
basicAuth:
users:
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
- "test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"
- "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"
```
### `insecure`
Enable the API in `insecure` mode, which means that the API will be available directly on the entryPoint named `traefik`.
!!! Note
!!! info
If the entryPoint named `traefik` is not configured, it will be automatically created on port 8080.
```toml tab="File (TOML)"
@ -138,7 +139,7 @@ api:
_Optional, Default=false_
Enable additional endpoints for debugging and profiling, served under `/debug/`.
Enable additional [endpoints](./api.md#endpoints) for debugging and profiling, served under `/debug/`.
```toml tab="File (TOML)"
[api]

8
docs/content/operations/cli.md
View file

@ -26,6 +26,10 @@ traefik [--flag=flag_argument] [-f [flag_argument]]
traefik [--flag[=true|false| ]] [-f [true|false| ]]
```
All flags are documented in the [(static configuration) CLI reference](../reference/static-configuration/cli.md).
!!! info "Flags are case insensitive."
### `healthcheck`
Calls Traefik `/ping` to check the health of Traefik.
@ -34,8 +38,8 @@ Its exit status is `0` if Traefik is healthy and `1` otherwise.
This can be used with Docker [HEALTHCHECK](https://docs.docker.com/engine/reference/builder/#healthcheck) instruction
or any other health check orchestration mechanism.
!!! note
The [`ping` endpoint](../ping/) must be enabled to allow the `healthcheck` command to call `/ping`.
!!! info
The [`ping` endpoint](../operations/ping.md) must be enabled to allow the `healthcheck` command to call `/ping`.
Usage:

8
docs/content/operations/dashboard.md
View file

@ -10,9 +10,11 @@ The dashboard is the central place that shows you the current active routes hand
<figcaption>The dashboard in action</figcaption>
</figure>
By default, the dashboard is available on `/` on port `:8080`.
By default, the dashboard is available on `/dashboard` on port `:8080`.
There is also a redirect of `/` to `/dashboard`, but one should not rely on that property as it is bound to change,
and it might make for confusing routing rules anyway.
!!! note "Did You Know?"
!!! info "Did You Know?"
It is possible to customize the dashboard endpoint.
To learn how, refer to the [API documentation](./api.md)
@ -55,6 +57,6 @@ api:
like authentication ([basicAuth](../middlewares/basicauth.md) , [digestAuth](../middlewares/digestauth.md), [forwardAuth](../middlewares/forwardauth.md)) or [whitelisting](../middlewares/ipwhitelist.md).
More information about `api@internal` can be found in the [API documentation](./api.md#configuration)
!!! note "Did You Know?"
!!! info "Did You Know?"
The API provides more features than the Dashboard.
To learn more about it, refer to the [API documentation](./api.md)

141
docs/content/providers/docker.md
View file

@ -37,7 +37,7 @@ Attach labels to your containers and let Traefik do the rest!
my-container:
# ...
labels:
- traefik.http.routers.my-container.rule=Host(`my-domain`)
- traefik.http.routers.my-container.rule=Host(`mydomain.com`)
```
??? example "Configuring Docker Swarm & Deploying / Exposing Services"
@ -76,18 +76,21 @@ Attach labels to your containers and let Traefik do the rest!
my-container:
deploy:
labels:
- traefik.http.routers.my-container.rule=Host(`my-domain`)
- traefik.http.routers.my-container.rule=Host(`mydomain.com`)
- traefik.http.services.my-container-service.loadbalancer.server.port=8080
```
!!! important "Labels in Docker Swarm Mode"
While in Swarm Mode, Traefik uses labels found on services, not on individual containers. Therefore, if you use a compose file with Swarm Mode, labels should be defined in the `deploy` part of your service.
While in Swarm Mode, Traefik uses labels found on services, not on individual containers.
Therefore, if you use a compose file with Swarm Mode, labels should be defined in the `deploy` part of your service.
This behavior is only enabled for docker-compose version 3+ ([Compose file reference](https://docs.docker.com/compose/compose-file/#labels-1)).
## Provider Configuration Options
## Routing Configuration
!!! tip "Browse the Reference"
If you're in a hurry, maybe you'd rather go through the [static](../reference/static-configuration/overview.md) and the [dynamic](../reference/dynamic-configuration/docker.md) configuration references.
See the dedicated section in [routing](../routing/providers/docker.md).
## Provider Configuration
### `endpoint`
@ -118,11 +121,11 @@ Traefik requires access to the docker socket to get its dynamic configuration.
`[...] only **trusted** users should be allowed to control your Docker daemon [...]`
!!! note "Improved Security"
!!! tip "Improved Security"
[TraefikEE](https://containo.us/traefikee) solves this problem by separating the control plane (connected to Docker) and the data plane (handling the requests).
??? tip "Resources about Docker's Security"
??? info "Resources about Docker's Security"
- [KubeCon EU 2018 Keynote, Running with Scissors, from Liz Rice](https://www.youtube.com/watch?v=ltrV-Qmh3oY)
- [Don't expose the Docker socket (not even to a container)](https://www.lvh.io/posts/dont-expose-the-docker-socket-not-even-to-a-container.html)
@ -141,14 +144,14 @@ Traefik requires access to the docker socket to get its dynamic configuration.
With Swarm mode, it allows scheduling of Traefik on worker nodes, with only the "socket exposer" container on the manager nodes.
- Accounting at kernel level, by enforcing kernel calls with mechanisms like [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux), to only allows an identified set of actions for Traefik's process (or the "socket exposer" process).
??? tip "Additional Resources"
??? info "Additional Resources"
- [Traefik issue GH-4174 about security with Docker socket](https://github.com/containous/traefik/issues/4174)
- [Inspecting Docker Activity with Socat](https://developers.redhat.com/blog/2015/02/25/inspecting-docker-activity-with-socat/)
- [Letting Traefik run on Worker Nodes](https://blog.mikesir87.io/2018/07/letting-traefik-run-on-worker-nodes/)
- [Docker Socket Proxy from Tecnativa](https://github.com/Tecnativa/docker-socket-proxy)
!!! note "Traefik & Swarm Mode"
!!! info "Traefik & Swarm Mode"
To let Traefik access the Docker Socket of the Swarm manager, it is mandatory to schedule Traefik on the Swarm manager nodes.
??? example "Using the docker.sock"
@ -159,7 +162,6 @@ Traefik requires access to the docker socket to get its dynamic configuration.
version: '3'
services:
traefik:
image: traefik:v2.0 # The official v2.0 Traefik docker image
ports:
@ -213,10 +215,10 @@ providers:
Traefik routes requests to the IP/Port of the matching container.
When setting `useBindPortIP=true`, you tell Traefik to use the IP/Port attached to the container's _binding_ instead of its inner network IP/Port.
When used in conjunction with the `traefik.http.services.XXX.loadbalancer.server.port` label (that tells Traefik to route requests to a specific port),
Traefik tries to find a binding on port `traefik.http.services.XXX.loadbalancer.server.port`.
When used in conjunction with the `traefik.http.services.<name>.loadbalancer.server.port` label (that tells Traefik to route requests to a specific port),
Traefik tries to find a binding on port `traefik.http.services.<name>.loadbalancer.server.port`.
If it can't find such a binding, Traefik falls back on the internal network IP of the container,
but still uses the `traefik.http.services.XXX.loadbalancer.server.port` that is set in the label.
but still uses the `traefik.http.services.<name>.loadbalancer.server.port` that is set in the label.
??? example "Examples of `usebindportip` in different situations."
@ -230,8 +232,13 @@ but still uses the `traefik.http.services.XXX.loadbalancer.server.port` that is
| LblPort | ExtIp:ExtPort:OtherPort | IntIp:LblPort |
| LblPort | ExtIp1:ExtPort1:IntPort1 & ExtIp2:LblPort:IntPort2 | ExtIp2:LblPort |
!!! note
In the above table, ExtIp stands for "external IP found in the binding", IntIp stands for "internal network container's IP", ExtPort stands for "external Port found in the binding", and IntPort stands for "internal network container's port."
!!! info ""
In the above table:
- `ExtIp` stands for "external IP found in the binding"
- `IntIp` stands for "internal network container's IP",
- `ExtPort` stands for "external Port found in the binding"
- `IntPort` stands for "internal network container's port."
### `exposedByDefault`
@ -430,7 +437,7 @@ _Optional_
#### `tls.ca`
TODO add description.
Certificate Authority used for the secured connection to Docker.
```toml tab="File (TOML)"
[providers.docker.tls]
@ -450,7 +457,12 @@ providers:
#### `tls.caOptional`
TODO add description.
Policy followed for the secured connection with TLS Client Authentication to Docker.
Requires `tls.ca` to be defined.
- `true`: VerifyClientCertIfGiven
- `false`: RequireAndVerifyClientCert
- if `tls.ca` is undefined NoClientCert
```toml tab="File (TOML)"
[providers.docker.tls]
@ -470,7 +482,7 @@ providers:
#### `tls.cert`
TODO add description.
Public certificate used for the secured connection to Docker.
```toml tab="File (TOML)"
[providers.docker.tls]
@ -493,7 +505,7 @@ providers:
#### `tls.key`
TODO add description.
Private certificate used for the secured connection to Docker.
```toml tab="File (TOML)"
[providers.docker.tls]
@ -516,7 +528,7 @@ providers:
#### `tls.insecureSkipVerify`
TODO add description.
If `insecureSkipVerify` is `true`, TLS for the connection to Docker accepts any certificate presented by the server and any host name in that certificate.
```toml tab="File (TOML)"
[providers.docker.tls]
@ -533,90 +545,3 @@ providers:
```bash tab="CLI"
--providers.docker.tls.insecureSkipVerify=true
```
## Routing Configuration Options
### General
Traefik creates, for each container, a corresponding [service](../routing/services/index.md) and [router](../routing/routers/index.md).
The Service automatically gets a server per instance of the container,
and the router automatically gets a rule defined by defaultRule (if no rule for it was defined in labels).
### Routers
To update the configuration of the Router automatically attached to the container, add labels starting with `traefik.http.routers.{name-of-your-choice}.` and followed by the option you want to change. For example, to change the rule, you could add the label `traefik.http.routers.my-container.rule=Host(my-domain)`.
Every [Router](../routing/routers/index.md) parameter can be updated this way.
### Services
To update the configuration of the Service automatically attached to the container, add labels starting with `traefik.http.services.{name-of-your-choice}.`, followed by the option you want to change. For example, to change the passhostheader behavior, you'd add the label `traefik.http.services.{name-of-your-choice}.loadbalancer.passhostheader=false`.
Every [Service](../routing/services/index.md) parameter can be updated this way.
### Middleware
You can declare pieces of middleware using labels starting with `traefik.http.middlewares.{name-of-your-choice}.`, followed by the middleware type/options. For example, to declare a middleware [`redirectscheme`](../middlewares/redirectscheme.md) named `my-redirect`, you'd write `traefik.http.middlewares.my-redirect.redirectscheme.scheme: https`.
??? example "Declaring and Referencing a Middleware"
```yaml
services:
my-container:
# ...
labels:
- traefik.http.middlewares.my-redirect.redirectscheme.scheme=https
- traefik.http.routers.my-container.middlewares=my-redirect
```
!!! warning "Conflicts in Declaration"
If you declare multiple middleware with the same name but with different parameters, the middleware fails to be declared.
More information about available middlewares in the dedicated [middlewares section](../middlewares/overview.md).
### TCP
You can declare TCP Routers and/or Services using labels.
??? example "Declaring TCP Routers and Services"
```yaml
services:
my-container:
# ...
labels:
- traefik.tcp.routers.my-router.rule="HostSNI(`my-host.com`)"
- traefik.tcp.routers.my-router.tls="true"
- traefik.tcp.services.my-service.loadbalancer.server.port="4123"
```
!!! warning "TCP and HTTP"
If you declare a TCP Router/Service, it will prevent Traefik from automatically creating an HTTP Router/Service (like it does by default if no TCP Router/Service is defined).
You can declare both a TCP Router/Service and an HTTP Router/Service for the same container (but you have to do so manually).
### Specific Options
#### `traefik.enable`
You can tell Traefik to consider (or not) the container by setting `traefik.enable` to true or false.
This option overrides the value of `exposedByDefault`.
#### `traefik.docker.network`
Overrides the default docker network to use for connections to the container.
If a container is linked to several networks, be sure to set the proper network name (you can check this with `docker inspect <container_id>`), otherwise it will randomly pick one (depending on how docker is returning them).
!!! warning
When deploying a stack from a compose file `stack`, the networks defined are prefixed with `stack`.
#### `traefik.docker.lbswarm`
Enables Swarm's inbuilt load balancer (only relevant in Swarm Mode).
If you enable this option, Traefik will use the virtual IP provided by docker swarm instead of the containers IPs.
Which means that Traefik will not perform any kind of load balancing and will delegate this task to swarm.

19
docs/content/providers/file.md
View file

@ -9,7 +9,7 @@ You can write these configuration elements:
* In [a dedicated file](#filename)
* In [several dedicated files](#directory)
!!! note
!!! info
The file provider is the default format used throughout the documentation to show samples of the configuration for many features.
!!! tip
@ -96,15 +96,12 @@ You can write these configuration elements:
passHostHeader: false
```
## Provider Configuration Options
## Provider Configuration
If you're in a hurry, maybe you'd rather go through the [dynamic configuration](../reference/dynamic-configuration/file.md) references and the [static configuration](../reference/static-configuration/overview.md).
!!! tip "Browse the Reference"
If you're in a hurry, maybe you'd rather go through the [static](../reference/static-configuration/overview.md) and the [dynamic](../reference/dynamic-configuration/file.md) configuration references.
### `filename`
_Optional_
Defines the path of the configuration file.
```toml tab="File (TOML)"
@ -125,8 +122,6 @@ providers:
### `directory`
_Optional_
Defines the directory that contains the configuration files.
```toml tab="File (TOML)"
@ -147,8 +142,6 @@ providers:
### `watch`
_Optional_
Set the `watch` option to `true` to allow Traefik to automatically watch for file changes.
It works with both the `filename` and the `directory` options.
@ -174,8 +167,8 @@ providers:
### Go Templating
!!! warning
Go Templating only works along with dedicated configuration files.
Templating does not work in the Traefik main configuration file.
Go Templating only works along with dedicated dynamic configuration files.
Templating does not work in the Traefik main static configuration file.
Traefik allows using Go templating.
Thus, it's possible to define easily lot of routers, services and TLS certificates as described in the file `template-rules.toml` :

201
docs/content/providers/kubernetes-crd.md
View file

@ -8,6 +8,10 @@ Traefik used to support Kubernetes only through the [Kubernetes Ingress provider
However, as the community expressed the need to benefit from Traefik features without resorting to (lots of) annotations,
we ended up writing a [Custom Resource Definition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) (alias CRD in the following) for an IngressRoute type, defined below, in order to provide a better way to configure access to a Kubernetes cluster.
## Resource Configuration
See the dedicated section in [routing](../routing/providers/kubernetes-crd.md).
## Provider Configuration
### `endpoint`
@ -189,203 +193,6 @@ providers:
--providers.kubernetescrd.throttleDuration="10s"
```
## Resource Configuration
If you're in a hurry, maybe you'd rather go through the [dynamic](../reference/dynamic-configuration/kubernetes-crd.md) configuration reference.
### Traefik IngressRoute definition
```yaml
--8<-- "content/providers/crd_ingress_route.yml"
```
That `IngressRoute` kind can then be used to define an `IngressRoute` object, such as in:
```yaml
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutefoo
spec:
entryPoints:
- web
routes:
# Match is the rule corresponding to an underlying router.
# Later on, match could be the simple form of a path prefix, e.g. just "/bar",
# but for now we only support a traefik style matching rule.
- match: Host(`foo.com`) && PathPrefix(`/bar`)
# kind could eventually be one of "Rule", "Path", "Host", "Method", "Header",
# "Parameter", etc, to support simpler forms of rule matching, but for now we
# only support "Rule".
kind: Rule
# (optional) Priority disambiguates rules of the same length, for route matching.
priority: 12
services:
- name: whoami
port: 80
# (default 1) A weight used by the weighted round-robin strategy (WRR).
weight: 1
# (default true) PassHostHeader controls whether to leave the request's Host
# Header as it was before it reached the proxy, or whether to let the proxy set it
# to the destination (backend) host.
passHostHeader: true
responseForwarding:
# (default 100ms) Interval between flushes of the buffered response body to the client.
flushInterval: 100ms
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRouteTCP
metadata:
name: ingressroutetcpfoo.crd
spec:
entryPoints:
- footcp
routes:
# Match is the rule corresponding to an underlying router.
- match: HostSNI(`*`)
services:
- name: whoamitcp
port: 8080
```
### Middleware
Additionally, to allow for the use of middlewares in an `IngressRoute`, we defined the CRD below for the `Middleware` kind.
```yaml
--8<-- "content/providers/crd_middlewares.yml"
```
Once the `Middleware` kind has been registered with the Kubernetes cluster, it can then be used in `IngressRoute` definitions, such as:
```yaml
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: stripprefix
namespace: foo
spec:
stripPrefix:
prefixes:
- /stripit
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutebar
spec:
entryPoints:
- web
routes:
- match: Host(`bar.com`) && PathPrefix(`/stripit`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: stripprefix
namespace: foo
```
!!! important "Cross-provider namespace"
As Kubernetes also has its own notion of namespace, one should not confuse the kubernetes namespace of a resource
(in the reference to the middleware) with the [provider namespace](../middlewares/overview.md#provider-namespace),
when the definition of the middleware is from another provider.
In this context, specifying a namespace when referring to the resource does not make any sense, and will be ignored.
More information about available middlewares in the dedicated [middlewares section](../middlewares/overview.md).
### TLS Option
Additionally, to allow for the use of TLS options in an IngressRoute, we defined the CRD below for the TLSOption kind.
More information about TLS Options is available in the dedicated [TLS Configuration Options](../../https/tls/#tls-options).
```yaml
--8<-- "content/providers/crd_tls_option.yml"
```
Once the TLSOption kind has been registered with the Kubernetes cluster or defined in the File Provider, it can then be used in IngressRoute definitions, such as:
```yaml
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: mytlsoption
namespace: default
spec:
minVersion: VersionTLS12
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutebar
spec:
entryPoints:
- web
routes:
- match: Host(`bar.com`) && PathPrefix(`/stripit`)
kind: Rule
services:
- name: whoami
port: 80
tls:
options:
name: mytlsoption
namespace: default
```
!!! important "References and namespaces"
If the optional `namespace` attribute is not set, the configuration will be applied with the namespace of the IngressRoute.
Additionally, when the definition of the TLS option is from another provider,
the cross-provider syntax (`middlewarename@provider`) should be used to refer to the TLS option,
just as in the [middleware case](../middlewares/overview.md#provider-namespace).
Specifying a namespace attribute in this case would not make any sense, and will be ignored.
### TLS
To allow for TLS, we made use of the `Secret` kind, as it was already defined, and it can be directly used in an `IngressRoute`:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: supersecret
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutetls
spec:
entryPoints:
- web
routes:
- match: Host(`foo.com`) && PathPrefix(`/bar`)
kind: Rule
services:
- name: whoami
port: 443
tls:
secretName: supersecret
```
## Further
Also see the [full example](../user-guides/crd-acme/index.md) with Let's Encrypt.

31
docs/content/providers/kubernetes-ingress.md
View file

@ -34,23 +34,20 @@ metadata:
spec:
rules:
- host: foo.com
http:
paths:
- path: /bar
backend:
serviceName: service1
servicePort: 80
- path: /foo
backend:
serviceName: service1
servicePort: 80
- host: foo.com
http:
paths:
- path: /bar
backend:
serviceName: service1
servicePort: 80
- path: /foo
backend:
serviceName: service1
servicePort: 80
```
## Provider Configuration Options
!!! tip "Browse the Reference"
If you're in a hurry, maybe you'd rather go through the [static](../reference/static-configuration/overview.md) configuration reference.
## Provider Configuration
### `endpoint`
@ -168,8 +165,8 @@ _Optional, Default: all namespaces (empty array)_
providers:
kubernetesIngress:
namespaces:
- "default"
- "production"
- "default"
- "production"
# ...
```

103
docs/content/providers/marathon.md
View file

@ -49,10 +49,11 @@ See also [Marathon user guide](../user-guides/marathon.md).
}
```
## Provider Configuration Options
## Routing Configuration
!!! tip "Browse the Reference"
If you're in a hurry, maybe you'd rather go through the [static](../reference/static-configuration/overview.md) and the [dynamic](../reference/dynamic-configuration/marathon.md) configuration references.
See the dedicated section in [routing](../routing/providers/marathon.md).
## Provider Configuration
### `basic`
@ -404,7 +405,7 @@ _Optional_
#### `tls.ca`
TODO add description.
Certificate Authority used for the secured connection to Marathon.
```toml tab="File (TOML)"
[providers.marathon.tls]
@ -424,7 +425,12 @@ providers:
#### `tls.caOptional`
TODO add description.
Policy followed for the secured connection to Marathon with TLS Client Authentication.
Requires `tls.ca` to be defined.
- `true`: VerifyClientCertIfGiven
- `false`: RequireAndVerifyClientCert
- if `tls.ca` is undefined NoClientCert
```toml tab="File (TOML)"
[providers.marathon.tls]
@ -444,7 +450,7 @@ providers:
#### `tls.cert`
TODO add description.
Public certificate used for the secured connection to Marathon.
```toml tab="File (TOML)"
[providers.marathon.tls]
@ -467,7 +473,7 @@ providers:
#### `tls.key`
TODO add description.
Private certificate used for the secured connection to Marathon.
```toml tab="File (TOML)"
[providers.marathon.tls]
@ -490,7 +496,7 @@ providers:
#### `tls.insecureSkipVerify`
TODO add description.
If `insecureSkipVerify` is `true`, TLS for the connection to Marathon accepts any certificate presented by the server and any host name in that certificate.
```toml tab="File (TOML)"
[providers.marathon.tls]
@ -584,84 +590,3 @@ providers:
```
Enables watching for Marathon changes.
## Routing Configuration Options
### General
Traefik creates, for each Marathon application, a corresponding [service](../routing/services/index.md) and [router](../routing/routers/index.md).
The Service automatically gets a server per instance of the application,
and the router automatically gets a rule defined by defaultRule (if no rule for it was defined in labels).
### Routers
To update the configuration of the Router automatically attached to the application,
add labels starting with `traefik.http.routers.{router-name-of-your-choice}.` and followed by the option you want to change.
For example, to change the routing rule, you could add the label ```traefik.http.routers.routername.rule=Host(`my-domain`)```.
Every [Router](../routing/routers/index.md) parameter can be updated this way.
### Services
To update the configuration of the Service automatically attached to the container,
add labels starting with `traefik.http.services.{service-name-of-your-choice}.`, followed by the option you want to change.
For example, to change the passHostHeader behavior, you'd add the label `traefik.http.services.servicename.loadbalancer.passhostheader=false`.
Every [Service](../routing/services/index.md) parameter can be updated this way.
### Middleware
You can declare pieces of middleware using labels starting with `traefik.http.middlewares.{middleware-name-of-your-choice}.`, followed by the middleware type/options.
For example, to declare a middleware [`redirectscheme`](../middlewares/redirectscheme.md) named `my-redirect`, you'd write `traefik.http.middlewares.my-redirect.redirectscheme.scheme: https`.
??? example "Declaring and Referencing a Middleware"
```json
{
...
"labels": {
"traefik.http.middlewares.my-redirect.redirectscheme.scheme": "https",
"traefik.http.routers.my-container.middlewares": "my-redirect"
}
}
```
!!! warning "Conflicts in Declaration"
If you declare multiple middleware with the same name but with different parameters, the middleware fails to be declared.
More information about available middlewares in the dedicated [middlewares section](../middlewares/overview.md).
### TCP
You can declare TCP Routers and/or Services using labels.
??? example "Declaring TCP Routers and Services"
```json
{
...
"labels": {
"traefik.tcp.routers.my-router.rule": "HostSNI(`my-host.com`)",
"traefik.tcp.routers.my-router.tls": "true",
"traefik.tcp.services.my-service.loadbalancer.server.port": "4123"
}
}
```
!!! warning "TCP and HTTP"
If you declare a TCP Router/Service, it will prevent Traefik from automatically creating an HTTP Router/Service (as it would by default if no TCP Router/Service is defined).
Both a TCP Router/Service and an HTTP Router/Service can be created for the same application, but it has to be done explicitly in the config.
### Specific Options
#### `traefik.enable`
Setting this option controls whether Traefik exposes the application.
It overrides the value of `exposedByDefault`.
#### `traefik.marathon.ipadressidx`
If a task has several IP addresses, this option specifies which one, in the list of available addresses, to select.

9
docs/content/providers/overview.md
View file

@ -32,12 +32,12 @@ Below is the list of the currently supported providers in Traefik.
| [Kubernetes](./kubernetes-crd.md) | Orchestrator | Custom Resource |
| [Marathon](./marathon.md) | Orchestrator | Label |
| [Rancher](./rancher.md) | Orchestrator | Label |
| [File](./file.md) | Manual | TOML format |
| [File](./file.md) | Manual | TOML/YAML format |
!!! note "More Providers"
!!! info "More Providers"
The current version of Traefik is in development and doesn't support (yet) every provider.
See the previous version (1.7) for more providers.
The current version of Traefik doesn't support (yet) every provider.
See the [previous version (v1.7)](https://docs.traefik.io/v1.7/) for more providers.
<!--
TODO (document TCP VS HTTP dynamic configuration)
@ -69,3 +69,4 @@ List of providers that support constraints:
- [Rancher](./rancher.md#constraints)
- [Marathon](./marathon.md#constraints)
- [Kubernetes CRD](./kubernetes-crd.md#labelselector)
- [Kubernetes Ingress](./kubernetes-ingress.md#labelselector)

70
docs/content/providers/rancher.md
View file

@ -7,8 +7,8 @@ A Story of Labels, Services & Containers
Attach labels to your services and let Traefik do the rest!
!!! important
This provider is specific to Rancher 1.x.
!!! important "This provider is specific to Rancher 1.x."
Rancher 2.x requires Kubernetes and does not have a metadata endpoint of its own for Traefik to query.
As such, Rancher 2.x users should utilize the [Kubernetes provider](./kubernetes-crd.md) directly.
@ -35,10 +35,14 @@ Attach labels to your services and let Traefik do the rest!
```yaml
labels:
- traefik.http.services.my-service.rule=Host(`my-domain`)
- traefik.http.services.my-service.rule=Host(`mydomain.com`)
```
## Provider Configuration Options
## Routing Configuration
See the dedicated section in [routing](../routing/providers/rancher.md).
## Provider Configuration
??? tip "Browse the Reference"
If you're in a hurry, maybe you'd rather go through the configuration reference:
@ -55,8 +59,6 @@ Attach labels to your services and let Traefik do the rest!
--8<-- "content/providers/rancher.txt"
```
List of all available labels for the [dynamic](../reference/dynamic-configuration/rancher.md) configuration references.
### `exposedByDefault`
_Optional, Default=true_
@ -274,59 +276,3 @@ The expression syntax is based on the `Label("key", "value")`, and `LabelRegex("
```
See also [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery).
## Routing Configuration Options
### General
Traefik creates, for each rancher service, a corresponding [service](../routing/services/index.md) and [router](../routing/routers/index.md).
The Service automatically gets a server per container in this rancher service, and the router gets a default rule attached to it, based on the service name.
### Routers
To update the configuration of the Router automatically attached to the container, add labels starting with `traefik.routers.{name-of-your-choice}.` and followed by the option you want to change.
For example, to change the rule, you could add the label `traefik.http.routers.my-container.rule=Host(my-domain)`.
Every [Router](../routing/routers/index.md) parameter can be updated this way.
### Services
To update the configuration of the Service automatically attached to the container, add labels starting with `traefik.http.services.{name-of-your-choice}.`,
followed by the option you want to change. For example, to change the passhostheader behavior,
you'd add the label `traefik.http.services.{name-of-your-choice}.loadbalancer.passhostheader=false`.
Every [Service](../routing/services/index.md) parameter can be updated this way.
### Middleware
You can declare pieces of middleware using labels starting with `traefik.http.middlewares.{name-of-your-choice}.`, followed by the middleware type/options.
For example, to declare a middleware [`redirectscheme`](../middlewares/redirectscheme.md) named `my-redirect`, you'd write `traefik.http.middlewares.my-redirect.redirectscheme.scheme: https`.
??? example "Declaring and Referencing a Middleware"
```yaml
# ...
labels:
- traefik.http.middlewares.my-redirect.redirectscheme.scheme=https
- traefik.http.routers.my-container.middlewares=my-redirect
```
!!! warning "Conflicts in Declaration"
If you declare multiple middleware with the same name but with different parameters, the middleware fails to be declared.
More information about available middlewares in the dedicated [middlewares section](../middlewares/overview.md).
### Specific Options
#### `traefik.enable`
You can tell Traefik to consider (or not) the container by setting `traefik.enable` to true or false.
This option overrides the value of `exposedByDefault`.
#### Port Lookup
Traefik is now capable of detecting the port to use, by following the default rancher flow.
That means, if you just expose lets say port :1337 on the rancher ui, traefik will pick up this port and use it.

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

@ -2,11 +2,11 @@ http:
routers:
Router0:
entryPoints:
- foobar
- foobar
- foobar
- foobar
middlewares:
- foobar
- foobar
- foobar
- foobar
service: foobar
rule: foobar
priority: 42
@ -14,21 +14,21 @@ http:
options: foobar
certResolver: foobar
domains:
- main: foobar
sans:
- foobar
- foobar
- main: foobar
sans:
- foobar
- foobar
- main: foobar
sans:
- foobar
- foobar
- main: foobar
sans:
- foobar
- foobar
Router1:
entryPoints:
- foobar
- foobar
- foobar
- foobar
middlewares:
- foobar
- foobar
- foobar
- foobar
service: foobar
rule: foobar
priority: 42
@ -36,14 +36,14 @@ http:
options: foobar
certResolver: foobar
domains:
- main: foobar
sans:
- foobar
- foobar
- main: foobar
sans:
- foobar
- foobar
- main: foobar
sans:
- foobar
- foobar
- main: foobar
sans:
- foobar
- foobar
services:
Service01:
loadBalancer:
@ -53,8 +53,8 @@ http:
secure: true
httpOnly: true
servers:
- url: foobar
- url: foobar
- url: foobar
- url: foobar
healthCheck:
scheme: foobar
path: foobar
@ -72,17 +72,17 @@ http:
mirroring:
service: foobar
mirrors:
- name: foobar
percent: 42
- name: foobar
percent: 42
- name: foobar
percent: 42
- name: foobar
percent: 42
Service03:
weighted:
services:
- name: foobar
weight: 42
- name: foobar
weight: 42
- name: foobar
weight: 42
- name: foobar
weight: 42
sticky:
cookie:
name: foobar
@ -95,8 +95,8 @@ http:
Middleware01:
basicAuth:
users:
- foobar
- foobar
- foobar
- foobar
usersFile: foobar
realm: foobar
removeHeader: true
@ -111,8 +111,8 @@ http:
Middleware03:
chain:
middlewares:
- foobar
- foobar
- foobar
- foobar
Middleware04:
circuitBreaker:
expression: foobar
@ -121,8 +121,8 @@ http:
Middleware06:
digestAuth:
users:
- foobar
- foobar
- foobar
- foobar
usersFile: foobar
removeHeader: true
realm: foobar
@ -130,8 +130,8 @@ http:
Middleware07:
errors:
status:
- foobar
- foobar
- foobar
- foobar
service: foobar
query: foobar
Middleware08:
@ -145,8 +145,8 @@ http:
insecureSkipVerify: true
trustForwardHeader: true
authResponseHeaders:
- foobar
- foobar
- foobar
- foobar
Middleware09:
headers:
customRequestHeaders:
@ -157,23 +157,23 @@ http:
name1: foobar
accessControlAllowCredentials: true
accessControlAllowHeaders:
- foobar
- foobar
- foobar
- foobar
accessControlAllowMethods:
- foobar
- foobar
- foobar
- foobar
accessControlAllowOrigin: foobar
accessControlExposeHeaders:
- foobar
- foobar
- foobar
- foobar
accessControlMaxAge: 42
addVaryHeader: true
allowedHosts:
- foobar
- foobar
- foobar
- foobar
hostsProxyHeaders:
- foobar
- foobar
- foobar
- foobar
sslRedirect: true
sslTemporaryRedirect: true
sslHost: foobar
@ -198,13 +198,13 @@ http:
Middleware10:
ipWhiteList:
sourceRange:
- foobar
- foobar
- foobar
- foobar
ipStrategy:
depth: 42
excludedIPs:
- foobar
- foobar
- foobar
- foobar
Middleware11:
inFlightReq:
amount: 42
@ -212,8 +212,8 @@ http:
ipstrategy:
depth: 42
excludedIPs:
- foobar
- foobar
- foobar
- foobar
requestHeaderName: foobar
requestHost: true
Middleware12:
@ -247,8 +247,8 @@ http:
ipstrategy:
depth: 42
excludedIPs:
- foobar
- foobar
- foobar
- foobar
requestHeaderName: foobar
requestHost: true
Middleware14:
@ -274,19 +274,19 @@ http:
Middleware19:
stripPrefix:
prefixes:
- foobar
- foobar
- foobar
- foobar
Middleware20:
stripPrefixRegex:
regex:
- foobar
- foobar
- foobar
- foobar
tcp:
routers:
TCPRouter0:
entryPoints:
- foobar
- foobar
- foobar
- foobar
service: foobar
rule: foobar
tls:
@ -294,18 +294,18 @@ tcp:
options: foobar
certResolver: foobar
domains:
- main: foobar
sans:
- foobar
- foobar
- main: foobar
sans:
- foobar
- foobar
- main: foobar
sans:
- foobar
- foobar
- main: foobar
sans:
- foobar
- foobar
TCPRouter1:
entryPoints:
- foobar
- foobar
- foobar
- foobar
service: foobar
rule: foobar
tls:
@ -313,60 +313,60 @@ tcp:
options: foobar
certResolver: foobar
domains:
- main: foobar
sans:
- foobar
- foobar
- main: foobar
sans:
- foobar
- foobar
- main: foobar
sans:
- foobar
- foobar
- main: foobar
sans:
- foobar
- foobar
services:
TCPService0:
loadBalancer:
terminationDelay: 100
servers:
- address: foobar
- address: foobar
- address: foobar
- address: foobar
TCPService1:
loadBalancer:
terminationDelay: 100
servers:
- address: foobar
- address: foobar
- address: foobar
- address: foobar
tls:
certificates:
- certFile: foobar
keyFile: foobar
stores:
- foobar
- foobar
- certFile: foobar
keyFile: foobar
stores:
- foobar
- foobar
- certFile: foobar
keyFile: foobar
stores:
- foobar
- foobar
- certFile: foobar
keyFile: foobar
stores:
- foobar
- foobar
options:
Options0:
minVersion: foobar
cipherSuites:
- foobar
- foobar
- foobar
- foobar
clientAuth:
caFiles:
- foobar
- foobar
- foobar
- foobar
clientAuthType: foobar
sniStrict: true
Options1:
minVersion: foobar
cipherSuites:
- foobar
- foobar
- foobar
- foobar
clientAuth:
caFiles:
- foobar
- foobar
- foobar
- foobar
clientAuthType: foobar
sniStrict: true
stores:

456
docs/content/routing/entrypoints.md
View file

@ -13,18 +13,21 @@ They define the port which will receive the requests (whether HTTP or TCP).
??? example "Port 80 only"
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
```
@ -33,6 +36,7 @@ They define the port which will receive the requests (whether HTTP or TCP).
??? example "Port 80 & 443"
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
@ -42,6 +46,7 @@ They define the port which will receive the requests (whether HTTP or TCP).
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
@ -51,13 +56,14 @@ They define the port which will receive the requests (whether HTTP or TCP).
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web-secure.address=:443
```
- Two entrypoints are defined: one called `web`, and the other called `web-secure`.
- `web` listens on port `80`, and `web-secure` on port `443`.
## Configuration
### General
@ -65,78 +71,341 @@ They define the port which will receive the requests (whether HTTP or TCP).
EntryPoints are part of the [static configuration](../getting-started/configuration-overview.md#the-static-configuration).
You can define them using a toml file, CLI arguments, or a key-value store.
See the complete reference for the list of available options:
??? info "See the complete reference for the list of available options"
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.name]
address = ":8888"
[entryPoints.name.transport]
[entryPoints.name.transport.lifeCycle]
requestAcceptGraceTimeout = 42
graceTimeOut = 42
[entryPoints.name.transport.respondingTimeouts]
readTimeout = 42
writeTimeout = 42
idleTimeout = 42
[entryPoints.name.proxyProtocol]
insecure = true
trustedIPs = ["127.0.0.1", "192.168.0.1"]
[entryPoints.name.forwardedHeaders]
insecure = true
trustedIPs = ["127.0.0.1", "192.168.0.1"]
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
lifeCycle:
requestAcceptGraceTimeout: 42
graceTimeOut: 42
respondingTimeouts:
readTimeout: 42
writeTimeout: 42
idleTimeout: 42
proxyProtocol:
insecure: true
trustedIPs:
- "127.0.0.1"
- "192.168.0.1"
forwardedHeaders:
insecure: true
trustedIPs:
- "127.0.0.1"
- "192.168.0.1"
```
```bash tab="CLI"
## Static configuration
--entryPoints.name.address=:8888
--entryPoints.name.transport.lifeCycle.requestAcceptGraceTimeout=42
--entryPoints.name.transport.lifeCycle.graceTimeOut=42
--entryPoints.name.transport.respondingTimeouts.readTimeout=42
--entryPoints.name.transport.respondingTimeouts.writeTimeout=42
--entryPoints.name.transport.respondingTimeouts.idleTimeout=42
--entryPoints.name.proxyProtocol.insecure=true
--entryPoints.name.proxyProtocol.trustedIPs="127.0.0.1,192.168.0.1"
--entryPoints.name.forwardedHeaders.insecure=true
--entryPoints.name.forwardedHeaders.trustedIPs="127.0.0.1,192.168.0.1"
```
```toml tab="File (TOML)"
[entryPoints]
### Forwarded Header
[entryPoints.EntryPoint0]
address = ":8888"
[entryPoints.EntryPoint0.transport]
[entryPoints.EntryPoint0.transport.lifeCycle]
requestAcceptGraceTimeout = 42
graceTimeOut = 42
[entryPoints.EntryPoint0.transport.respondingTimeouts]
readTimeout = 42
writeTimeout = 42
idleTimeout = 42
[entryPoints.EntryPoint0.proxyProtocol]
insecure = true
trustedIPs = ["foobar", "foobar"]
[entryPoints.EntryPoint0.forwardedHeaders]
insecure = true
trustedIPs = ["foobar", "foobar"]
```
You can configure Traefik to trust the forwarded headers information (`X-Forwarded-*`).
```yaml tab="File (YAML)"
entryPoints:
??? info "`forwardedHeaders.trustedIPs`"
Trusting Forwarded Headers from specific IPs.
EntryPoint0:
address: ":8888"
transport:
lifeCycle:
requestAcceptGraceTimeout: 42
graceTimeOut: 42
respondingTimeouts:
readTimeout: 42
writeTimeout: 42
idleTimeout: 42
proxyProtocol:
insecure: true
trustedIPs:
- "foobar"
- "foobar"
forwardedHeaders:
insecure: true
trustedIPs:
- "foobar"
- "foobar"
```
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web.forwardedHeaders]
trustedIPs = ["127.0.0.1/32", "192.168.1.7"]
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
forwardedHeaders:
trustedIPs:
- "127.0.0.1/32"
- "192.168.1.7"
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.forwardedHeaders.trustedIPs=127.0.0.1/32,192.168.1.7
```
```bash tab="CLI"
--entryPoints.EntryPoint0.address=:8888
--entryPoints.EntryPoint0.transport.lifeCycle.requestAcceptGraceTimeout=42
--entryPoints.EntryPoint0.transport.lifeCycle.graceTimeOut=42
--entryPoints.EntryPoint0.transport.respondingTimeouts.readTimeout=42
--entryPoints.EntryPoint0.transport.respondingTimeouts.writeTimeout=42
--entryPoints.EntryPoint0.transport.respondingTimeouts.idleTimeout=42
--entryPoints.EntryPoint0.proxyProtocol.insecure=true
--entryPoints.EntryPoint0.proxyProtocol.trustedIPs=foobar,foobar
--entryPoints.EntryPoint0.forwardedHeaders.insecure=true
--entryPoints.EntryPoint0.forwardedHeaders.trustedIPs=foobar,foobar
```
??? info "`forwardedHeaders.insecure`"
Insecure Mode (Always Trusting Forwarded Headers).
## ProxyProtocol
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web.forwardedHeaders]
insecure = true
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
forwardedHeaders:
insecure: true
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=:80
--entryPoints.web.forwardedHeaders.insecure
```
### Transport
#### `respondingTimeouts`
`respondingTimeouts` are timeouts for incoming requests to the Traefik instance.
??? info "`transport.respondingTimeouts.readTimeout`"
_Optional, Default=0s_
`readTimeout` is the maximum duration for reading the entire request, including the body.
If zero, no timeout exists.
Can be provided in a format supported by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration) or as raw values (digits).
If no units are provided, the value is parsed assuming seconds.
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.name]
address = ":8888"
[entryPoints.name.transport]
[entryPoints.name.transport.respondingTimeouts]
readTimeout = 42
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
respondingTimeouts:
readTimeout: 42
```
```bash tab="CLI"
## Static configuration
--entryPoints.name.address=:8888
--entryPoints.name.transport.respondingTimeouts.readTimeout=42
```
??? info "`transport.respondingTimeouts.writeTimeout`"
_Optional, Default=0s_
`writeTimeout` is the maximum duration before timing out writes of the response.
It covers the time from the end of the request header read to the end of the response write.
If zero, no timeout exists.
Can be provided in a format supported by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration) or as raw values (digits).
If no units are provided, the value is parsed assuming seconds.
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.name]
address = ":8888"
[entryPoints.name.transport]
[entryPoints.name.transport.respondingTimeouts]
writeTimeout = 42
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
respondingTimeouts:
writeTimeout: 42
```
```bash tab="CLI"
## Static configuration
--entryPoints.name.address=:8888
--entryPoints.name.transport.respondingTimeouts.writeTimeout=42
```
??? info "`transport.respondingTimeouts.idleTimeout`"
_Optional, Default=180s_
`idleTimeout` is the maximum duration an idle (keep-alive) connection will remain idle before closing itself.
If zero, no timeout exists.
Can be provided in a format supported by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration) or as raw values (digits).
If no units are provided, the value is parsed assuming seconds.
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.name]
address = ":8888"
[entryPoints.name.transport]
[entryPoints.name.transport.respondingTimeouts]
idleTimeout = 42
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
respondingTimeouts:
idleTimeout: 42
```
```bash tab="CLI"
## Static configuration
--entryPoints.name.address=:8888
--entryPoints.name.transport.respondingTimeouts.idleTimeout=42
```
#### `lifeCycle`
Controls the behavior of Traefik during the shutdown phase.
??? info "`lifeCycle.requestAcceptGraceTimeout`"
_Optional, Default=0s_
Duration to keep accepting requests prior to initiating the graceful termination period (as defined by the `graceTimeOut` option).
This option is meant to give downstream load-balancers sufficient time to take Traefik out of rotation.
Can be provided in a format supported by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration) or as raw values (digits).
If no units are provided, the value is parsed assuming seconds.
The zero duration disables the request accepting grace period, i.e., Traefik will immediately proceed to the grace period.
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.name]
address = ":8888"
[entryPoints.name.transport]
[entryPoints.name.transport.lifeCycle]
requestAcceptGraceTimeout = 42
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
lifeCycle:
requestAcceptGraceTimeout: 42
```
```bash tab="CLI"
## Static configuration
--entryPoints.name.address=:8888
--entryPoints.name.transport.lifeCycle.requestAcceptGraceTimeout=42
```
??? info "`lifeCycle.graceTimeOut`"
_Optional, Default=10s_
Duration to give active requests a chance to finish before Traefik stops.
Can be provided in a format supported by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration) or as raw values (digits).
If no units are provided, the value is parsed assuming seconds.
!!! warning "In this time frame no new requests are accepted."
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.name]
address = ":8888"
[entryPoints.name.transport]
[entryPoints.name.transport.lifeCycle]
graceTimeOut = 42
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
name:
address: ":8888"
transport:
lifeCycle:
graceTimeOut: 42
```
```bash tab="CLI"
## Static configuration
--entryPoints.name.address=:8888
--entryPoints.name.transport.lifeCycle.graceTimeOut=42
```
### ProxyProtocol
Traefik supports [ProxyProtocol](https://www.haproxy.org/download/2.0/doc/proxy-protocol.txt) version 1 and 2.
If proxyprotocol header parsing is enabled for the entry point, this entry point can accept connections with or without proxyprotocol headers.
If Proxy Protocol header parsing is enabled for the entry point, this entry point can accept connections with or without Proxy Protocol headers.
If the proxyprotocol header is passed, then the version is determined automatically.
If the Proxy Protocol header is passed, then the version is determined automatically.
??? example "Enabling Proxy Protocol with Trusted IPs"
??? info "`proxyProtocol.trustedIPs`"
Enabling Proxy Protocol with Trusted IPs.
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
@ -146,13 +415,14 @@ If the proxyprotocol header is passed, then the version is determined automatica
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
proxyProtocol:
trustedIPs:
- "127.0.0.1/32"
- "192.168.1.7"
- "127.0.0.1/32"
- "192.168.1.7"
```
```bash tab="CLI"
@ -161,13 +431,16 @@ If the proxyprotocol header is passed, then the version is determined automatica
```
IPs in `trustedIPs` only will lead to remote client address replacement: Declare load-balancer IPs or CIDR range here.
??? example "Insecure Mode -- Testing Environment Only"
??? info "`proxyProtocol.insecure`"
Insecure Mode (Testing Environment Only).
In a test environments, you can configure Traefik to trust every incoming connection.
Doing so, every remote client address will be replaced (`trustedIPs` won't have any effect)
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
@ -177,6 +450,7 @@ If the proxyprotocol header is passed, then the version is determined automatica
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
@ -193,57 +467,3 @@ If the proxyprotocol header is passed, then the version is determined automatica
When queuing Traefik behind another load-balancer, make sure to configure Proxy Protocol on both sides.
Not doing so could introduce a security risk in your system (enabling request forgery).
## Forwarded Header
You can configure Traefik to trust the forwarded headers information (`X-Forwarded-*`)
??? example "Trusting Forwarded Headers from specific IPs"
```toml tab="File (TOML)"
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web.forwardedHeaders]
trustedIPs = ["127.0.0.1/32", "192.168.1.7"]
```
```yaml tab="File (YAML)"
entryPoints:
web:
address: ":80"
forwardedHeaders:
trustedIPs:
- "127.0.0.1/32"
- "192.168.1.7"
```
```bash tab="CLI"
--entryPoints.web.address=:80
--entryPoints.web.forwardedHeaders.trustedIPs=127.0.0.1/32,192.168.1.7
```
??? example "Insecure Mode -- Always Trusting Forwarded Headers"
```toml tab="File (TOML)"
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web.forwardedHeaders]
insecure = true
```
```yaml tab="File (YAML)"
entryPoints:
web:
address: ":80"
forwardedHeaders:
insecure: true
```
```bash tab="CLI"
--entryPoints.web.address=:80
--entryPoints.web.forwardedHeaders.insecure
```

8
docs/content/routing/overview.md
View file

@ -112,19 +112,19 @@ http:
- url: http://private/whoami-service
```
!!! note "The File Provider"
!!! info ""
In this example, we use the [file provider](../providers/file.md).
Even if it is one of the least magical way of configuring Traefik, it explicitly describes every available notion.
!!! note "HTTP / TCP"
!!! info "HTTP / TCP"
In this example, we've defined routing rules for http requests only.
Traefik also supports TCP requests. To add [TCP routers](./routers/index.md) and [TCP services](./services/index.md), declare them in a TCP section like in the following.
??? example "Adding a TCP route for TLS requests on whoami.traefik.io"
Static configuration:
**Static Configuration**
```toml tab="File (TOML)"
[entryPoints]
@ -157,7 +157,7 @@ http:
--providers.file.filename=dynamic_conf.toml
```
Dynamic configuration:
**Dynamic Configuration**
```toml tab="TOML"
# http routing section

0
docs/content/providers/crd_ingress_route.yml → docs/content/routing/providers/crd_ingress_route.yml
View file

0
docs/content/providers/crd_middlewares.yml → docs/content/routing/providers/crd_middlewares.yml
View file

0
docs/content/providers/crd_tls_option.yml → docs/content/routing/providers/crd_tls_option.yml
View file

491
docs/content/routing/providers/docker.md Normal file
View file

@ -0,0 +1,491 @@
# Traefik & Docker
A Story of Labels & Containers
{: .subtitle }
![Docker](../../assets/img/providers/docker.png)
Attach labels to your containers and let Traefik do the rest!
## Configuration Examples
??? example "Configuring Docker & Deploying / Exposing Services"
Enabling the docker provider
```toml tab="File (TOML)"
[providers.docker]
```
```yaml tab="File (YAML)"
providers:
docker: {}
```
```bash tab="CLI"
--providers.docker=true
```
Attaching labels to containers (in your docker compose file)
```yaml
version: "3"
services:
my-container:
# ...
labels:
- traefik.http.routers.my-container.rule=Host(`mydomain.com`)
```
??? example "Configuring Docker Swarm & Deploying / Exposing Services"
Enabling the docker provider (Swarm Mode)
```toml tab="File (TOML)"
[providers.docker]
# swarm classic (1.12-)
# endpoint = "tcp://127.0.0.1:2375"
# docker swarm mode (1.12+)
endpoint = "tcp://127.0.0.1:2377"
swarmMode = true
```
```yaml tab="File (YAML)"
providers:
docker:
# swarm classic (1.12-)
# endpoint = "tcp://127.0.0.1:2375"
# docker swarm mode (1.12+)
endpoint: "tcp://127.0.0.1:2375"
swarmMode: true
```
```bash tab="CLI"
--providers.docker.endpoint="tcp://127.0.0.1:2375"
--providers.docker.swarmMode=true
```
Attach labels to services (not to containers) while in Swarm mode (in your docker compose file)
```yaml
version: "3"
services:
my-container:
deploy:
labels:
- traefik.http.routers.my-container.rule=Host(`mydomain.com`)
- traefik.http.services.my-container-service.loadbalancer.server.port=8080
```
!!! important "Labels in Docker Swarm Mode"
While in Swarm Mode, Traefik uses labels found on services, not on individual containers.
Therefore, if you use a compose file with Swarm Mode, labels should be defined in the `deploy` part of your service.
This behavior is only enabled for docker-compose version 3+ ([Compose file reference](https://docs.docker.com/compose/compose-file/#labels-1)).
## Routing Configuration
!!! info "Labels"
- Labels are case insensitive.
- The complete list of labels can be found [the reference page](../../reference/dynamic-configuration/docker.md)
### General
Traefik creates, for each container, a corresponding [service](../services/index.md) and [router](../routers/index.md).
The Service automatically gets a server per instance of the container,
and the router automatically gets a rule defined by `defaultRule` (if no rule for it was defined in labels).
### Routers
To update the configuration of the Router automatically attached to the container,
add labels starting with `traefik.http.routers.<name-of-your-choice>.` and followed by the option you want to change.
For example, to change the rule, you could add the label ```traefik.http.routers.my-container.rule=Host(`mydomain.com`)```.
??? info "`traefik.http.routers.<router_name>.rule`"
See [rule](../routers/index.md#rule) for more information.
```yaml
- "traefik.http.routers.myrouter.rule=Host(`mydomain.com`)"
```
??? info "`traefik.http.routers.<router_name>.entrypoints`"
See [entry points](../routers/index.md#entrypoints) for more information.
```yaml
- "traefik.http.routers.myrouter.entrypoints=web,websecure"
```
??? info "`traefik.http.routers.<router_name>.middlewares`"
See [middlewares](../routers/index.md#middlewares) and [middlewares overview](../../middlewares/overview.md) for more information.
```yaml
- "traefik.http.routers.myrouter.middlewares=auth,prefix,cb"
```
??? info "`traefik.http.routers.<router_name>.service`"
See [rule](../routers/index.md#service) for more information.
```yaml
- "traefik.http.routers.myrouter.service=myservice"
```
??? info "`traefik.http.routers.<router_name>.tls`"
See [tls](../routers/index.md#tls) for more information.
```yaml
- "traefik.http.routers.myrouter>.tls=true"
```
??? info "`traefik.http.routers.<router_name>.tls.certresolver`"
See [certResolver](../routers/index.md#certresolver) for more information.
```yaml
- "traefik.http.routers.myrouter.tls.certresolver=myresolver"
```
??? info "`traefik.http.routers.<router_name>.tls.domains[n].main`"
See [domains](../routers/index.md#domains) for more information.
```yaml
- "traefik.http.routers.myrouter.tls.domains[0].main=foobar.com"
```
??? info "`traefik.http.routers.<router_name>.tls.domains[n].sans`"
See [domains](../routers/index.md#domains) for more information.
```yaml
- "traefik.http.routers.myrouter.tls.domains[0].sans=test.foobar.com,dev.foobar.com"
```
??? info "`traefik.http.routers.<router_name>.tls.options`"
See [options](../routers/index.md#options) for more information.
```yaml
- "traefik.http.routers.myrouter.tls.options=foobar"
```
??? info "`traefik.http.routers.<router_name>.priority`"
<!-- TODO doc priority in routers page -->
```yaml
- "traefik.http.routers.myrouter.priority=42"
```
### Services
To update the configuration of the Service automatically attached to the container,
add labels starting with `traefik.http.services.<name-of-your-choice>.`, followed by the option you want to change.
For example, to change the `passHostHeader` behavior,
you'd add the label `traefik.http.services.<name-of-your-choice>.loadbalancer.passhostheader=false`.
??? info "`traefik.http.services.<service_name>.loadbalancer.server.port`"
Registers a port.
Useful when the container exposes multiples ports.
Mandatory for Docker Swarm.
```yaml
- "traefik.http.services.myservice.loadbalancer.server.port=8080"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.server.scheme`"
Overrides the default scheme.
```yaml
- "traefik.http.services.myservice.loadbalancer.server.scheme=http"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.passhostheader`"
<!-- TODO doc passHostHeader in services page -->
```yaml
- "traefik.http.services.myservice.loadbalancer.passhostheader=true"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.headers.<header_name>`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.headers.X-Foo=foobar"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.hostname`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.hostname=foobar.com"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.interval`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.interval=10"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.path`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.path=/foo"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.port`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.port=42"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.scheme`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.scheme=http"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.timeout`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.timeout=10"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.sticky`"
See [sticky sessions](../services/index.md#sticky-sessions) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.sticky=true"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.httponly`"
See [sticky sessions](../services/index.md#sticky-sessions) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.sticky.cookie.httponly=true"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.name`"
See [sticky sessions](../services/index.md#sticky-sessions) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.sticky.cookie.name=foobar"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.secure`"
See [sticky sessions](../services/index.md#sticky-sessions) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.sticky.cookie.secure=true"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.responseforwarding.flushinterval`"
<!-- TODO doc responseforwarding in services page -->
FlushInterval specifies the flush interval to flush to the client while copying the response body.
```yaml
- "traefik.http.services.myservice.loadbalancer.responseforwarding.flushinterval=10"
```
### Middleware
You can declare pieces of middleware using labels starting with `traefik.http.middlewares.<name-of-your-choice>.`,
followed by the middleware type/options.
For example, to declare a middleware [`redirectscheme`](../../middlewares/redirectscheme.md) named `my-redirect`,
you'd write `traefik.http.middlewares.my-redirect.redirectscheme.scheme=https`.
More information about available middlewares in the dedicated [middlewares section](../../middlewares/overview.md).
??? example "Declaring and Referencing a Middleware"
```yaml
services:
my-container:
# ...
labels:
# Declaring a middleware
- traefik.http.middlewares.my-redirect.redirectscheme.scheme=https
# Referencing a middleware
- traefik.http.routers.my-container.middlewares=my-redirect
```
!!! warning "Conflicts in Declaration"
If you declare multiple middleware with the same name but with different parameters, the middleware fails to be declared.
### TCP
You can declare TCP Routers and/or Services using labels.
??? example "Declaring TCP Routers and Services"
```yaml
services:
my-container:
# ...
labels:
- "traefik.tcp.routers.my-router.rule=HostSNI(`my-host.com`)"
- "traefik.tcp.routers.my-router.tls=true"
- "traefik.tcp.services.my-service.loadbalancer.server.port=4123"
```
!!! warning "TCP and HTTP"
If you declare a TCP Router/Service, it will prevent Traefik from automatically creating an HTTP Router/Service (like it does by default if no TCP Router/Service is defined).
You can declare both a TCP Router/Service and an HTTP Router/Service for the same container (but you have to do so manually).
#### TCP Routers
??? info "`traefik.tcp.routers.<router_name>.entrypoints`"
See [entry points](../routers/index.md#entrypoints_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.entrypoints=ep1,ep2"
```
??? info "`traefik.tcp.routers.<router_name>.rule`"
See [rule](../routers/index.md#rule_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.rule=HostSNI(`myhost.com`)"
```
??? info "`traefik.tcp.routers.<router_name>.service`"
See [service](../routers/index.md#services) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.service=myservice"
```
??? info "`traefik.tcp.routers.<router_name>.tls`"
See [TLS](../routers/index.md#tls_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.tls=true"
```
??? info "`traefik.tcp.routers.<router_name>.tls.certresolver`"
See [certResolver](../routers/index.md#certresolver_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.tls.certresolver=myresolver"
```
??? info "`traefik.tcp.routers.<router_name>.tls.domains[n].main`"
See [domains](../routers/index.md#domains_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.tls.domains[0].main=foobar.com"
```
??? info "`traefik.tcp.routers.<router_name>.tls.domains[n].sans`"
See [domains](../routers/index.md#domains_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.tls.domains[0].sans=test.foobar.com,dev.foobar.com"
```
??? info "`traefik.tcp.routers.<router_name>.tls.options`"
See [options](../routers/index.md#options_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.tls.options=mysoptions"
```
??? info "`traefik.tcp.routers.<router_name>.tls.passthrough`"
See [TLS](../routers/index.md#tls_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.tls.passthrough=true"
```
#### TCP Services
??? info "`traefik.tcp.services.<service_name>.loadbalancer.server.port`"
Registers a port of the application.
```yaml
- "traefik.tcp.services.mytcpservice.loadbalancer.server.port=423"
```
??? info "`traefik.tcp.services.<service_name>.loadbalancer.terminationdelay`"
See [termination delay](../services/index.md#termination-delay) for more information.
```yaml
- "traefik.tcp.services.mytcpservice.loadbalancer.terminationdelay=100"
```
### Specific Provider Options
#### `traefik.enable`
```yaml
- "traefik.enable=true"
```
You can tell Traefik to consider (or not) the container by setting `traefik.enable` to true or false.
This option overrides the value of `exposedByDefault`.
#### `traefik.docker.network`
```yaml
- "traefik.docker.network=mynetwork"
```
Overrides the default docker network to use for connections to the container.
If a container is linked to several networks, be sure to set the proper network name (you can check this with `docker inspect <container_id>`),
otherwise it will randomly pick one (depending on how docker is returning them).
!!! warning
When deploying a stack from a compose file `stack`, the networks defined are prefixed with `stack`.
#### `traefik.docker.lbswarm`
```yaml
- "traefik.docker.lbswarm=true"
```
Enables Swarm's inbuilt load balancer (only relevant in Swarm Mode).
If you enable this option, Traefik will use the virtual IP provided by docker swarm instead of the containers IPs.
Which means that Traefik will not perform any kind of load balancing and will delegate this task to swarm.

205
docs/content/routing/providers/kubernetes-crd.md Normal file
View file

@ -0,0 +1,205 @@
# Traefik & Kubernetes
The Kubernetes Ingress Controller, The Custom Resource Way.
{: .subtitle }
## Resource Configuration
If you're in a hurry, maybe you'd rather go through the [dynamic configuration](../../reference/dynamic-configuration/kubernetes-crd.md) reference.
### Traefik IngressRoute definition
```yaml
--8<-- "content/routing/providers/crd_ingress_route.yml"
```
That `IngressRoute` kind can then be used to define an `IngressRoute` object, such as in:
```yaml
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutefoo
spec:
entryPoints:
- web
routes:
# Match is the rule corresponding to an underlying router.
# Later on, match could be the simple form of a path prefix, e.g. just "/bar",
# but for now we only support a traefik style matching rule.
- match: Host(`foo.com`) && PathPrefix(`/bar`)
# kind could eventually be one of "Rule", "Path", "Host", "Method", "Header",
# "Parameter", etc, to support simpler forms of rule matching, but for now we
# only support "Rule".
kind: Rule
# (optional) Priority disambiguates rules of the same length, for route matching.
priority: 12
services:
- name: whoami
port: 80
# (default 1) A weight used by the weighted round-robin strategy (WRR).
weight: 1
# (default true) PassHostHeader controls whether to leave the request's Host
# Header as it was before it reached the proxy, or whether to let the proxy set it
# to the destination (backend) host.
passHostHeader: true
responseForwarding:
# (default 100ms) Interval between flushes of the buffered response body to the client.
flushInterval: 100ms
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRouteTCP
metadata:
name: ingressroutetcpfoo.crd
spec:
entryPoints:
- footcp
routes:
# Match is the rule corresponding to an underlying router.
- match: HostSNI(`*`)
services:
- name: whoamitcp
port: 8080
```
### Middleware
Additionally, to allow for the use of middlewares in an `IngressRoute`, we defined the CRD below for the `Middleware` kind.
```yaml
--8<-- "content/routing/providers/crd_middlewares.yml"
```
Once the `Middleware` kind has been registered with the Kubernetes cluster, it can then be used in `IngressRoute` definitions, such as:
```yaml
apiVersion: traefik.containo.us/v1alpha1
kind: Middleware
metadata:
name: stripprefix
namespace: foo
spec:
stripPrefix:
prefixes:
- /stripit
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutebar
spec:
entryPoints:
- web
routes:
- match: Host(`bar.com`) && PathPrefix(`/stripit`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: stripprefix
namespace: foo
```
!!! important "Cross-provider namespace"
As Kubernetes also has its own notion of namespace, one should not confuse the kubernetes namespace of a resource
(in the reference to the middleware) with the [provider namespace](../../middlewares/overview.md#provider-namespace),
when the definition of the middleware is from another provider.
In this context, specifying a namespace when referring to the resource does not make any sense, and will be ignored.
More information about available middlewares in the dedicated [middlewares section](../../middlewares/overview.md).
### TLS Option
Additionally, to allow for the use of TLS options in an IngressRoute, we defined the CRD below for the TLSOption kind.
More information about TLS Options is available in the dedicated [TLS Configuration Options](../../../https/tls/#tls-options).
```yaml
--8<-- "content/routing/providers/crd_tls_option.yml"
```
Once the TLSOption kind has been registered with the Kubernetes cluster or defined in the File Provider, it can then be used in IngressRoute definitions, such as:
```yaml
apiVersion: traefik.containo.us/v1alpha1
kind: TLSOption
metadata:
name: mytlsoption
namespace: default
spec:
minVersion: VersionTLS12
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutebar
spec:
entryPoints:
- web
routes:
- match: Host(`bar.com`) && PathPrefix(`/stripit`)
kind: Rule
services:
- name: whoami
port: 80
tls:
options:
name: mytlsoption
namespace: default
```
!!! important "References and namespaces"
If the optional `namespace` attribute is not set, the configuration will be applied with the namespace of the IngressRoute.
Additionally, when the definition of the TLS option is from another provider,
the cross-provider syntax (`middlewarename@provider`) should be used to refer to the TLS option,
just as in the [middleware case](../../middlewares/overview.md#provider-namespace).
Specifying a namespace attribute in this case would not make any sense, and will be ignored.
### TLS
To allow for TLS, we made use of the `Secret` kind, as it was already defined, and it can be directly used in an `IngressRoute`:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: supersecret
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=
---
apiVersion: traefik.containo.us/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutetls
spec:
entryPoints:
- web
routes:
- match: Host(`foo.com`) && PathPrefix(`/bar`)
kind: Rule
services:
- name: whoami
port: 443
tls:
secretName: supersecret
```
## Further
Also see the [full example](../../user-guides/crd-acme/index.md) with Let's Encrypt.

392
docs/content/routing/providers/marathon.md Normal file
View file

@ -0,0 +1,392 @@
# Traefik & Marathon
Traefik can be configured to use Marathon as a provider.
{: .subtitle }
See also [Marathon user guide](../../user-guides/marathon.md).
## Routing Configuration
!!! info "Labels"
- Labels are case insensitive.
- The complete list of labels can be found [the reference page](../../reference/dynamic-configuration/marathon.md)
### General
Traefik creates, for each Marathon application, a corresponding [service](../services/index.md) and [router](../routers/index.md).
The Service automatically gets a server per instance of the application,
and the router automatically gets a rule defined by defaultRule (if no rule for it was defined in labels).
### Routers
To update the configuration of the Router automatically attached to the application,
add labels starting with `traefik.http.routers.{router-name-of-your-choice}.` and followed by the option you want to change.
For example, to change the routing rule, you could add the label ```"traefik.http.routers.routername.rule": "Host(`mydomain.com`)"```.
??? info "`traefik.http.routers.<router_name>.rule`"
See [rule](../routers/index.md#rule) for more information.
```json
"traefik.http.routers.myrouter.rule": "Host(`mydomain.com`)"
```
??? info "`traefik.http.routers.<router_name>.entrypoints`"
See [entry points](../routers/index.md#entrypoints) for more information.
```json
"traefik.http.routers.myrouter.entrypoints": "web,websecure"
```
??? info "`traefik.http.routers.<router_name>.middlewares`"
See [middlewares](../routers/index.md#middlewares) and [middlewares overview](../../middlewares/overview.md) for more information.
```json
"traefik.http.routers.myrouter.middlewares": "auth,prefix,cb"
```
??? info "`traefik.http.routers.<router_name>.service`"
See [rule](../routers/index.md#service) for more information.
```json
"traefik.http.routers.myrouter.service": "myservice"
```
??? info "`traefik.http.routers.<router_name>.tls`"
See [tls](../routers/index.md#tls) for more information.
```json
"traefik.http.routers.myrouter>.tls": "true"
```
??? info "`traefik.http.routers.<router_name>.tls.certresolver`"
See [certResolver](../routers/index.md#certresolver) for more information.
```json
"traefik.http.routers.myrouter.tls.certresolver": "myresolver"
```
??? info "`traefik.http.routers.<router_name>.tls.domains[n].main`"
See [domains](../routers/index.md#domains) for more information.
```json
"traefik.http.routers.myrouter.tls.domains[0].main": "foobar.com"
```
??? info "`traefik.http.routers.<router_name>.tls.domains[n].sans`"
See [domains](../routers/index.md#domains) for more information.
```json
"traefik.http.routers.myrouter.tls.domains[0].sans": "test.foobar.com,dev.foobar.com"
```
??? info "`traefik.http.routers.<router_name>.tls.options`"
See [options](../routers/index.md#options) for more information.
```json
"traefik.http.routers.myrouter.tls.options": "foobar"
```
??? info "`traefik.http.routers.<router_name>.priority`"
<!-- TODO doc priority in routers page -->
```json
"traefik.http.routers.myrouter.priority": "42"
```
### Services
To update the configuration of the Service automatically attached to the container,
add labels starting with `traefik.http.services.{service-name-of-your-choice}.`, followed by the option you want to change.
For example, to change the passHostHeader behavior, you'd add the label `"traefik.http.services.servicename.loadbalancer.passhostheader": "false"`.
??? info "`traefik.http.services.<service_name>.loadbalancer.server.port`"
Registers a port.
Useful when the container exposes multiples ports.
```json
"traefik.http.services.myservice.loadbalancer.server.port": "8080"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.server.scheme`"
Overrides the default scheme.
```json
"traefik.http.services.myservice.loadbalancer.server.scheme": "http"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.passhostheader`"
<!-- TODO doc passHostHeader in services page -->
```json
"traefik.http.services.myservice.loadbalancer.passhostheader": "true"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.headers.<header_name>`"
See [health check](../services/index.md#health-check) for more information.
```json
"traefik.http.services.myservice.loadbalancer.healthcheck.headers.X-Foo": "foobar"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.hostname`"
See [health check](../services/index.md#health-check) for more information.
```json
"traefik.http.services.myservice.loadbalancer.healthcheck.hostname": "foobar.com"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.interval`"
See [health check](../services/index.md#health-check) for more information.
```json
"traefik.http.services.myservice.loadbalancer.healthcheck.interval": "10"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.path`"
See [health check](../services/index.md#health-check) for more information.
```json
"traefik.http.services.myservice.loadbalancer.healthcheck.path": "/foo"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.port`"
See [health check](../services/index.md#health-check) for more information.
```json
"traefik.http.services.myservice.loadbalancer.healthcheck.port": "42"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.scheme`"
See [health check](../services/index.md#health-check) for more information.
```json
"traefik.http.services.myservice.loadbalancer.healthcheck.scheme": "http"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.timeout`"
See [health check](../services/index.md#health-check) for more information.
```json
"traefik.http.services.myservice.loadbalancer.healthcheck.timeout": "10"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.sticky`"
See [sticky sessions](../services/index.md#sticky-sessions) for more information.
```json
"traefik.http.services.myservice.loadbalancer.sticky": "true"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.httponly`"
See [sticky sessions](../services/index.md#sticky-sessions) for more information.
```json
"traefik.http.services.myservice.loadbalancer.sticky.cookie.httponly": "true"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.name`"
See [sticky sessions](../services/index.md#sticky-sessions) for more information.
```json
"traefik.http.services.myservice.loadbalancer.sticky.cookie.name": "foobar"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.secure`"
See [sticky sessions](../services/index.md#sticky-sessions) for more information.
```json
"traefik.http.services.myservice.loadbalancer.sticky.cookie.secure": "true"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.responseforwarding.flushinterval`"
<!-- TODO doc responseforwarding in services page -->
FlushInterval specifies the flush interval to flush to the client while copying the response body.
```json
"traefik.http.services.myservice.loadbalancer.responseforwarding.flushinterval": "10"
```
### Middleware
You can declare pieces of middleware using labels starting with `traefik.http.middlewares.{middleware-name-of-your-choice}.`, followed by the middleware type/options.
For example, to declare a middleware [`redirectscheme`](../../middlewares/redirectscheme.md) named `my-redirect`, you'd write `"traefik.http.middlewares.my-redirect.redirectscheme.scheme": "https"`.
More information about available middlewares in the dedicated [middlewares section](../../middlewares/overview.md).
??? example "Declaring and Referencing a Middleware"
```json
{
...
"labels": {
"traefik.http.middlewares.my-redirect.redirectscheme.scheme": "https",
"traefik.http.routers.my-container.middlewares": "my-redirect"
}
}
```
!!! warning "Conflicts in Declaration"
If you declare multiple middleware with the same name but with different parameters, the middleware fails to be declared.
### TCP
You can declare TCP Routers and/or Services using labels.
??? example "Declaring TCP Routers and Services"
```json
{
...
"labels": {
"traefik.tcp.routers.my-router.rule": "HostSNI(`my-host.com`)",
"traefik.tcp.routers.my-router.tls": "true",
"traefik.tcp.services.my-service.loadbalancer.server.port": "4123"
}
}
```
!!! warning "TCP and HTTP"
If you declare a TCP Router/Service, it will prevent Traefik from automatically creating an HTTP Router/Service (like it does by default if no TCP Router/Service is defined).
You can declare both a TCP Router/Service and an HTTP Router/Service for the same container (but you have to do so manually).
#### TCP Routers
??? info "`traefik.tcp.routers.<router_name>.entrypoints`"
See [entry points](../routers/index.md#entrypoints_1) for more information.
```json
"traefik.tcp.routers.mytcprouter.entrypoints": "ep1,ep2"
```
??? info "`traefik.tcp.routers.<router_name>.rule`"
See [rule](../routers/index.md#rule_1) for more information.
```json
"traefik.tcp.routers.mytcprouter.rule": "HostSNI(`myhost.com`)"
```
??? info "`traefik.tcp.routers.<router_name>.service`"
See [service](../routers/index.md#services) for more information.
```json
"traefik.tcp.routers.mytcprouter.service": "myservice"
```
??? info "`traefik.tcp.routers.<router_name>.tls`"
See [TLS](../routers/index.md#tls_1) for more information.
```json
"traefik.tcp.routers.mytcprouter.tls": "true
```
??? info "`traefik.tcp.routers.<router_name>.tls.certresolver`"
See [certResolver](../routers/index.md#certresolver_1) for more information.
```json
"traefik.tcp.routers.mytcprouter.tls.certresolver": "myresolver"
```
??? info "`traefik.tcp.routers.<router_name>.tls.domains[n].main`"
See [domains](../routers/index.md#domains_1) for more information.
```json
"traefik.tcp.routers.mytcprouter.tls.domains[0].main": "foobar.com"
```
??? info "`traefik.tcp.routers.<router_name>.tls.domains[n].sans`"
See [domains](../routers/index.md#domains_1) for more information.
```json
"traefik.tcp.routers.mytcprouter.tls.domains[0].sans": "test.foobar.com,dev.foobar.com"
```
??? info "`traefik.tcp.routers.<router_name>.tls.options`"
See [options](../routers/index.md#options_1) for more information.
```json
"traefik.tcp.routers.mytcprouter.tls.options": "mysoptions"
```
??? info "`traefik.tcp.routers.<router_name>.tls.passthrough`"
See [TLS](../routers/index.md#tls_1) for more information.
```json
"traefik.tcp.routers.mytcprouter.tls.passthrough": "true"
```
#### TCP Services
??? info "`traefik.tcp.services.<service_name>.loadbalancer.server.port`"
Registers a port of the application.
```json
"traefik.tcp.services.mytcpservice.loadbalancer.server.port": "423"
```
??? info "`traefik.tcp.services.<service_name>.loadbalancer.terminationdelay`"
See [termination delay](../services/index.md#termination-delay) for more information.
```json
"traefik.tcp.services.mytcpservice.loadbalancer.terminationdelay": "100"
```
### Specific Provider Options
#### `traefik.enable`
```json
"traefik.enable": "true"
```
Setting this option controls whether Traefik exposes the application.
It overrides the value of `exposedByDefault`.
#### `traefik.marathon.ipadressidx`
```json
"traefik.marathon.ipadressidx": "1"
```
If a task has several IP addresses, this option specifies which one, in the list of available addresses, to select.

393
docs/content/routing/providers/rancher.md Normal file
View file

@ -0,0 +1,393 @@
# Traefik & Rancher
A Story of Labels, Services & Containers
{: .subtitle }
![Rancher](../../assets/img/providers/rancher.png)
Attach labels to your services and let Traefik do the rest!
!!! important "This provider is specific to Rancher 1.x."
Rancher 2.x requires Kubernetes and does not have a metadata endpoint of its own for Traefik to query.
As such, Rancher 2.x users should utilize the [Kubernetes provider](./kubernetes-crd.md) directly.
## Routing Configuration
!!! info "Labels"
- Labels are case insensitive.
- The complete list of labels can be found [the reference page](../../reference/dynamic-configuration/rancher.md)
### General
Traefik creates, for each rancher service, a corresponding [service](../services/index.md) and [router](../routers/index.md).
The Service automatically gets a server per container in this rancher service, and the router gets a default rule attached to it, based on the service name.
### Routers
To update the configuration of the Router automatically attached to the container, add labels starting with `traefik.routers.{name-of-your-choice}.` and followed by the option you want to change.
For example, to change the rule, you could add the label ```traefik.http.routers.my-container.rule=Host(`mydomain.com`)```.
??? info "`traefik.http.routers.<router_name>.rule`"
See [rule](../routers/index.md#rule) for more information.
```yaml
- "traefik.http.routers.myrouter.rule=Host(`mydomain.com`)"
```
??? info "`traefik.http.routers.<router_name>.entrypoints`"
See [entry points](../routers/index.md#entrypoints) for more information.
```yaml
- "traefik.http.routers.myrouter.entrypoints=web,websecure"
```
??? info "`traefik.http.routers.<router_name>.middlewares`"
See [middlewares](../routers/index.md#middlewares) and [middlewares overview](../../middlewares/overview.md) for more information.
```yaml
- "traefik.http.routers.myrouter.middlewares=auth,prefix,cb"
```
??? info "`traefik.http.routers.<router_name>.service`"
See [rule](../routers/index.md#service) for more information.
```yaml
- "traefik.http.routers.myrouter.service=myservice"
```
??? info "`traefik.http.routers.<router_name>.tls`"
See [tls](../routers/index.md#tls) for more information.
```yaml
- "traefik.http.routers.myrouter>.tls=true"
```
??? info "`traefik.http.routers.<router_name>.tls.certresolver`"
See [certResolver](../routers/index.md#certresolver) for more information.
```yaml
- "traefik.http.routers.myrouter.tls.certresolver=myresolver"
```
??? info "`traefik.http.routers.<router_name>.tls.domains[n].main`"
See [domains](../routers/index.md#domains) for more information.
```yaml
- "traefik.http.routers.myrouter.tls.domains[0].main=foobar.com"
```
??? info "`traefik.http.routers.<router_name>.tls.domains[n].sans`"
See [domains](../routers/index.md#domains) for more information.
```yaml
- "traefik.http.routers.myrouter.tls.domains[0].sans=test.foobar.com,dev.foobar.com"
```
??? info "`traefik.http.routers.<router_name>.tls.options`"
See [options](../routers/index.md#options) for more information.
```yaml
- "traefik.http.routers.myrouter.tls.options=foobar"
```
??? info "`traefik.http.routers.<router_name>.priority`"
<!-- TODO doc priority in routers page -->
```yaml
- "traefik.http.routers.myrouter.priority=42"
```
### Services
To update the configuration of the Service automatically attached to the container,
add labels starting with `traefik.http.services.{name-of-your-choice}.`, followed by the option you want to change.
For example, to change the `passHostHeader` behavior,
you'd add the label `traefik.http.services.{name-of-your-choice}.loadbalancer.passhostheader=false`.
??? info "`traefik.http.services.<service_name>.loadbalancer.server.port`"
Registers a port.
Useful when the container exposes multiples ports.
```yaml
- "traefik.http.services.myservice.loadbalancer.server.port=8080"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.server.scheme`"
Overrides the default scheme.
```yaml
- "traefik.http.services.myservice.loadbalancer.server.scheme=http"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.passhostheader`"
<!-- TODO doc passHostHeader in services page -->
```yaml
- "traefik.http.services.myservice.loadbalancer.passhostheader=true"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.headers.<header_name>`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.headers.X-Foo=foobar"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.hostname`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.hostname=foobar.com"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.interval`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.interval=10"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.path`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.path=/foo"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.port`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.port=42"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.scheme`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.scheme=http"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.timeout`"
See [health check](../services/index.md#health-check) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.healthcheck.timeout=10"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.sticky`"
See [sticky sessions](../services/index.md#sticky-sessions) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.sticky=true"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.httponly`"
See [sticky sessions](../services/index.md#sticky-sessions) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.sticky.cookie.httponly=true"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.name`"
See [sticky sessions](../services/index.md#sticky-sessions) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.sticky.cookie.name=foobar"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.secure`"
See [sticky sessions](../services/index.md#sticky-sessions) for more information.
```yaml
- "traefik.http.services.myservice.loadbalancer.sticky.cookie.secure=true"
```
??? info "`traefik.http.services.<service_name>.loadbalancer.responseforwarding.flushinterval`"
<!-- TODO doc responseforwarding in services page -->
FlushInterval specifies the flush interval to flush to the client while copying the response body.
```yaml
- "traefik.http.services.myservice.loadbalancer.responseforwarding.flushinterval=10"
```
### Middleware
You can declare pieces of middleware using labels starting with `traefik.http.middlewares.{name-of-your-choice}.`, followed by the middleware type/options.
For example, to declare a middleware [`redirectscheme`](../../middlewares/redirectscheme.md) named `my-redirect`, you'd write `traefik.http.middlewares.my-redirect.redirectscheme.scheme: https`.
More information about available middlewares in the dedicated [middlewares section](../../middlewares/overview.md).
??? example "Declaring and Referencing a Middleware"
```yaml
# ...
labels:
# Declaring a middleware
- traefik.http.middlewares.my-redirect.redirectscheme.scheme=https
# Referencing a middleware
- traefik.http.routers.my-container.middlewares=my-redirect
```
!!! warning "Conflicts in Declaration"
If you declare multiple middleware with the same name but with different parameters, the middleware fails to be declared.
### TCP
You can declare TCP Routers and/or Services using labels.
??? example "Declaring TCP Routers and Services"
```yaml
services:
my-container:
# ...
labels:
- "traefik.tcp.routers.my-router.rule=HostSNI(`my-host.com`)"
- "traefik.tcp.routers.my-router.tls=true"
- "traefik.tcp.services.my-service.loadbalancer.server.port=4123"
```
!!! warning "TCP and HTTP"
If you declare a TCP Router/Service, it will prevent Traefik from automatically creating an HTTP Router/Service (like it does by default if no TCP Router/Service is defined).
You can declare both a TCP Router/Service and an HTTP Router/Service for the same container (but you have to do so manually).
#### TCP Routers
??? info "`traefik.tcp.routers.<router_name>.entrypoints`"
See [entry points](../routers/index.md#entrypoints_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.entrypoints=ep1,ep2"
```
??? info "`traefik.tcp.routers.<router_name>.rule`"
See [rule](../routers/index.md#rule_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.rule=HostSNI(`myhost.com`)"
```
??? info "`traefik.tcp.routers.<router_name>.service`"
See [service](../routers/index.md#services) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.service=myservice"
```
??? info "`traefik.tcp.routers.<router_name>.tls`"
See [TLS](../routers/index.md#tls_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.tls=true"
```
??? info "`traefik.tcp.routers.<router_name>.tls.certresolver`"
See [certResolver](../routers/index.md#certresolver_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.tls.certresolver=myresolver"
```
??? info "`traefik.tcp.routers.<router_name>.tls.domains[n].main`"
See [domains](../routers/index.md#domains_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.tls.domains[0].main=foobar.com"
```
??? info "`traefik.tcp.routers.<router_name>.tls.domains[n].sans`"
See [domains](../routers/index.md#domains_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.tls.domains[0].sans=test.foobar.com,dev.foobar.com"
```
??? info "`traefik.tcp.routers.<router_name>.tls.options`"
See [options](../routers/index.md#options_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.tls.options=mysoptions"
```
??? info "`traefik.tcp.routers.<router_name>.tls.passthrough`"
See [TLS](../routers/index.md#tls_1) for more information.
```yaml
- "traefik.tcp.routers.mytcprouter.tls.passthrough=true"
```
#### TCP Services
??? info "`traefik.tcp.services.<service_name>.loadbalancer.server.port`"
Registers a port of the application.
```yaml
- "traefik.tcp.services.mytcpservice.loadbalancer.server.port=423"
```
??? info "`traefik.tcp.services.<service_name>.loadbalancer.terminationdelay`"
See [termination delay](../services/index.md#termination-delay) for more information.
```yaml
- "traefik.tcp.services.mytcpservice.loadbalancer.terminationdelay=100"
```
### Specific Provider Options
#### `traefik.enable`
```yaml
- "traefik.enable=true"
```
You can tell Traefik to consider (or not) the container by setting `traefik.enable` to true or false.
This option overrides the value of `exposedByDefault`.
#### Port Lookup
Traefik is capable of detecting the port to use, by following the default rancher flow.
That means, if you just expose lets say port `:1337` on the rancher ui, traefik will pick up this port and use it.

520
docs/content/routing/routers/index.md
View file

@ -13,84 +13,74 @@ In the process, routers may use pieces of [middleware](../../middlewares/overvie
??? example "Requests /foo are Handled by service-foo -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
[http.routers]
[http.routers.my-router]
rule = "Path(`/foo`)"
service = "service-foo"
## Dynamic configuration
[http.routers]
[http.routers.my-router]
rule = "Path(`/foo`)"
service = "service-foo"
```
```yaml tab="YAML"
http:
routers:
my-router:
rule: "Path(`/foo`)"
service: service-foo
```
??? example "With a [middleware](../../middlewares/overview.md) -- using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
[http.routers]
[http.routers.my-router]
rule = "Path(`/foo`)"
# declared elsewhere
middlewares = ["authentication"]
service = "service-foo"
```
```yaml tab="YAML"
http:
routers:
my-router:
rule: "Path(`/foo`)"
# declared elsewhere
middlewares:
- authentication
service: service-foo
## Dynamic configuration
http:
routers:
my-router:
rule: "Path(`/foo`)"
service: service-foo
```
??? example "Forwarding all (non-tls) requests on port 3306 to a database service"
```toml tab="TOML"
## Static configuration ##
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.mysql-default]
address = ":3306"
## Dynamic configuration ##
**Dynamic Configuration**
```toml tab="File (TOML)"
## Dynamic configuration
[tcp]
[tcp.routers]
[tcp.routers.to-database]
entryPoints = ["mysql-default"]
entryPoints = ["mysql"]
# Catch every request (only available rule for non-tls routers. See below.)
rule = "HostSNI(`*`)"
service = "database"
```
```yaml tab="YAML"
## Static configuration ##
entryPoints:
web:
address: ":80"
mysql-default:
address: ":3306"
## Dynamic configuration ##
```yaml tab="File (YAML)"
## Dynamic configuration
tcp:
routers:
to-database:
entryPoints:
- "mysql-default"
- "mysql"
# Catch every request (only available rule for non-tls routers. See below.)
rule: "HostSNI(`*`)"
service: database
```
**Static Configuration**
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.mysql]
address = ":3306"
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
mysql:
address: ":3306"
```
```bash tab="CLI"
## Static configuration
--entryPoints.web.address=":80"
--entryPoints.mysql.address=":3306"
```
## Configuring HTTP Routers
@ -101,20 +91,10 @@ If you want to limit the router scope to a set of entry points, set the `entryPo
??? example "Listens to Every EntryPoint"
```toml tab="TOML"
## Static configuration ##
**Dynamic Configuration**
[entryPoints]
[entryPoints.web]
# ...
[entryPoints.web-secure]
# ...
[entryPoints.other]
# ...
## Dynamic configuration ##
```toml tab="File (TOML)"
## Dynamic configuration
[http.routers]
[http.routers.Router-1]
# By default, routers listen to every entry points
@ -122,19 +102,8 @@ If you want to limit the router scope to a set of entry points, set the `entryPo
service = "service-1"
```
```yaml tab="YAML"
## Static configuration ##
entryPoints:
web:
# ...
web-secure:
# ...
other:
# ...
## Dynamic configuration ##
```yaml tab="File (YAML)"
## Dynamic configuration
http:
routers:
Router-1:
@ -142,66 +111,108 @@ If you want to limit the router scope to a set of entry points, set the `entryPo
rule: "Host(`traefik.io`)"
service: "service-1"
```
**Static Configuration**
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.websecure]
address = ":443"
[entryPoints.other]
address = ":9090"
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
other:
address: ":9090"
```
```bash tab="CLI"
## Static configuration
--entrypoints.web.address=":80"
--entrypoints.websecure.address=":443"
--entrypoints.other.address=":9090"
```
??? example "Listens to Specific EntryPoints"
```toml tab="TOML"
## Static configuration ##
[entryPoints]
[entryPoints.web]
# ...
[entryPoints.web-secure]
# ...
[entryPoints.other]
# ...
## Dynamic configuration ##
**Dynamic Configuration**
```toml tab="File (TOML)"
## Dynamic configuration
[http.routers]
[http.routers.Router-1]
# won't listen to entry point web
entryPoints = ["web-secure", "other"]
entryPoints = ["websecure", "other"]
rule = "Host(`traefik.io`)"
service = "service-1"
```
```yaml tab="YAML"
## Static configuration ##
entryPoints:
web:
# ...
web-secure:
# ...
other:
# ...
## Dynamic configuration ##
```yaml tab="File (YAML)"
## Dynamic configuration
http:
routers:
Router-1:
# won't listen to entry point web
entryPoints:
- "web-secure"
- "other"
- "websecure"
- "other"
rule: "Host(`traefik.io`)"
service: "service-1"
```
**Static Configuration**
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.websecure]
address = ":443"
[entryPoints.other]
address = ":9090"
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
other:
address: ":9090"
```
```bash tab="CLI"
## Static configuration
--entrypoints.web.address=":80"
--entrypoints.websecure.address=":443"
--entrypoints.other.address=":9090"
```
### Rule
Rules are a set of matchers that determine if a particular request matches specific criteria.
If the rule is verified, the router becomes active, calls middlewares, and then forwards the request to the service.
??? example "Host is traefik.io"
!!! example "Host is traefik.io"
```toml
rule = "Host(`traefik.io`)"
```
??? example "Host is traefik.io OR Host is containo.us AND path is /traefik"
!!! example "Host is traefik.io OR Host is containo.us AND path is /traefik"
```toml
rule = "Host(`traefik.io`) || (Host(`containo.us`) && Path(`/traefik`))"
@ -226,7 +237,7 @@ The table below lists all the available matchers:
you must declare an arbitrarily named variable followed by the colon-separated regular expression, all enclosed in curly braces.
Any pattern supported by [Go's regexp package](https://golang.org/pkg/regexp/) may be used (example: `/posts/{id:[0-9]+}`).
!!! tip "Combining Matchers Using Operators and Parenthesis"
!!! info "Combining Matchers Using Operators and Parenthesis"
You can combine multiple matchers using the AND (`&&`) and OR (`||`) operators. You can also use parenthesis.
@ -234,7 +245,7 @@ The table below lists all the available matchers:
The rule is evaluated "before" any middleware has the opportunity to work, and "before" the request is forwarded to the service.
!!! tip "Path Vs PathPrefix"
!!! info "Path Vs PathPrefix"
Use `Path` if your service listens on the exact path only. For instance, `Path: /products` would match `/products` but not `/products/shoes`.
@ -247,14 +258,40 @@ The table below lists all the available matchers:
You can attach a list of [middlewares](../../middlewares/overview.md) to each HTTP router.
The middlewares will take effect only if the rule matches, and before forwarding the request to the service.
!!! tip "Middlewares order"
Middlewares are applied in the same order as their declaration in **router**.
??? example "With a [middleware](../../middlewares/overview.md) -- using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[http.routers]
[http.routers.my-router]
rule = "Path(`/foo`)"
# declared elsewhere
middlewares = ["authentication"]
service = "service-foo"
```
```yaml tab="YAML"
## Dynamic configuration
http:
routers:
my-router:
rule: "Path(`/foo`)"
# declared elsewhere
middlewares:
- authentication
service: service-foo
```
### Service
You must attach a [service](../services/index.md) per router.
Services are the target for the router.
!!! note "HTTP Only"
HTTP routers can only target HTTP services (not TCP services).
!!! important "HTTP routers can only target HTTP services (not TCP services)."
### TLS
@ -265,7 +302,8 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted
??? example "Configuring the router to accept HTTPS requests only"
```toml tab="TOML"
```toml tab="File (TOML)"
## Dynamic configuration
[http.routers]
[http.routers.Router-1]
rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
@ -274,7 +312,8 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted
[http.routers.Router-1.tls]
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
## Dynamic configuration
http:
routers:
Router-1:
@ -284,17 +323,19 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted
tls: {}
```
!!! note "HTTPS & ACME"
!!! info "HTTPS & ACME"
In the current version, with [ACME](../../https/acme.md) enabled, automatic certificate generation will apply to every router declaring a TLS section.
!!! important "Routers for HTTP & HTTPS"
If you need to define the same route for both HTTP and HTTPS requests, you will need to define two different routers: one with the tls section, one without.
If you need to define the same route for both HTTP and HTTPS requests, you will need to define two different routers:
one with the tls section, one without.
??? example "HTTP & HTTPS routes"
```toml tab="TOML"
```toml tab="File (TOML)"
## Dynamic configuration
[http.routers]
[http.routers.my-https-router]
rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
@ -307,7 +348,8 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted
service = "service-id"
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
## Dynamic configuration
http:
routers:
my-https-router:
@ -326,15 +368,20 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted
The `options` field enables fine-grained control of the TLS parameters.
It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied only if a `Host` rule is defined.
!!! note "Server Name Association"
!!! info "Server Name Association"
Even though one might get the impression that a TLS options reference is mapped to a router, or a router rule, one should realize that it is actually mapped only to the host name found in the `Host` part of the rule. Of course, there could also be several `Host` parts in a rule, in which case the TLS options reference would be mapped to as many host names.
Even though one might get the impression that a TLS options reference is mapped to a router, or a router rule,
one should realize that it is actually mapped only to the host name found in the `Host` part of the rule.
Of course, there could also be several `Host` parts in a rule, in which case the TLS options reference would be mapped to as many host names.
Another thing to keep in mind is: the TLS option is picked from the mapping mentioned above and based on the server name provided during the TLS handshake, and it all happens before routing actually occurs.
Another thing to keep in mind is:
the TLS option is picked from the mapping mentioned above and based on the server name provided during the TLS handshake,
and it all happens before routing actually occurs.
??? example "Configuring the TLS options"
```toml tab="TOML"
```toml tab="File (TOML)"
## Dynamic configuration
[http.routers]
[http.routers.Router-1]
rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
@ -352,7 +399,8 @@ It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied
]
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
## Dynamic configuration
http:
routers:
Router-1:
@ -367,15 +415,18 @@ It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied
foo:
minVersion: VersionTLS12
cipherSuites:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
```
!!! important "Conflicting TLS Options"
Since a TLS options reference is mapped to a host name, if a configuration introduces a situation where the same host name (from a `Host` rule) gets matched with two TLS options references, a conflict occurs, such as in the example below:
Since a TLS options reference is mapped to a host name,
if a configuration introduces a situation where the same host name (from a `Host` rule) gets matched with two TLS options references,
a conflict occurs, such as in the example below:
```toml tab="TOML"
```toml tab="File (TOML)"
## Dynamic configuration
[http.routers]
[http.routers.routerfoo]
rule = "Host(`snitest.com`) && Path(`/foo`)"
@ -389,7 +440,8 @@ It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied
options = "bar"
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
## Dynamic configuration
http:
routers:
routerfoo:
@ -409,7 +461,8 @@ It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied
If `certResolver` is defined, Traefik will try to generate certificates based on routers `Host` & `HostSNI` rules.
```toml tab="TOML"
```toml tab="File (TOML)"
## Dynamic configuration
[http.routers]
[http.routers.routerfoo]
rule = "Host(`snitest.com`) && Path(`/foo`)"
@ -417,7 +470,8 @@ If `certResolver` is defined, Traefik will try to generate certificates based on
certResolver = "foo"
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
## Dynamic configuration
http:
routers:
routerfoo:
@ -426,8 +480,8 @@ http:
certResolver: foo
```
!!! note "Multiple Hosts in a Rule"
The rule `Host(test1.traefik.io,test2.traefik.io)` will request a certificate with the main domain `test1.traefik.io` and SAN `test2.traefik.io`.
!!! info "Multiple Hosts in a Rule"
The rule ```Host(`test1.traefik.io`,`test2.traefik.io`)``` will request a certificate with the main domain `test1.traefik.io` and SAN `test2.traefik.io`.
#### `domains`
@ -435,7 +489,8 @@ You can set SANs (alternative domains) for each main domain.
Every domain must have A/AAAA records pointing to Traefik.
Each domain & SAN will lead to a certificate request.
```toml tab="TOML"
```toml tab="File (TOML)"
## Dynamic configuration
[http.routers]
[http.routers.routerbar]
rule = "Host(`snitest.com`) && Path(`/bar`)"
@ -443,10 +498,11 @@ Each domain & SAN will lead to a certificate request.
certResolver = "bar"
[[http.routers.routerbar.tls.domains]]
main = "snitest.com"
sans = "*.snitest.com"
sans = ["*.snitest.com"]
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
## Dynamic configuration
http:
routers:
routerbar:
@ -454,8 +510,8 @@ http:
tls:
certResolver: "bar"
domains:
- main: "snitest.com"
sans: "*.snitest.com"
- main: "snitest.com"
sans: "*.snitest.com"
```
[ACME v2](https://community.letsencrypt.org/t/acme-v2-and-wildcard-certificate-support-is-live/55579) supports wildcard certificates.
@ -466,13 +522,12 @@ In this case the generated DNS TXT record for both domains is the same.
Even though this behavior is [DNS RFC](https://community.letsencrypt.org/t/wildcard-issuance-two-txt-records-for-the-same-name/54528/2) compliant,
it can lead to problems as all DNS providers keep DNS records cached for a given time (TTL) and this TTL can be greater than the challenge timeout making the `DNS-01` challenge fail.
The Traefik ACME client library [LEGO](https://github.com/go-acme/lego) supports some but not all DNS providers to work around this issue.
The [Supported `provider` table](../../https/acme.md#providers) indicates if they allow generating certificates for a wildcard domain and its root domain.
The Traefik ACME client library [lego](https://github.com/go-acme/lego) supports some but not all DNS providers to work around this issue.
The [supported `provider` table](../../https/acme.md#providers) indicates if they allow generating certificates for a wildcard domain and its root domain.
!!! note
Wildcard certificates can only be verified through a [`DNS-01` challenge](../../https/acme.md#dnschallenge).
!!! important "Wildcard certificates can only be verified through a [`DNS-01` challenge](../../https/acme.md#dnschallenge)."
!!! note "Double Wildcard Certificates"
!!! warning "Double Wildcard Certificates"
It is not possible to request a double wildcard certificate for a domain (for example `*.*.local.com`).
## Configuring TCP Routers
@ -488,19 +543,11 @@ If not specified, TCP routers will accept requests from all defined entry points
If you want to limit the router scope to a set of entry points, set the entry points option.
??? example "Listens to Every Entry Point"
**Dynamic Configuration**
```toml tab="TOML"
## Static configuration ##
[entryPoints]
[entryPoints.web]
# ...
[entryPoints.web-secure]
# ...
[entryPoints.other]
# ...
## Dynamic configuration ##
```toml tab="File (TOML)"
## Dynamic configuration
[tcp.routers]
[tcp.routers.Router-1]
@ -511,18 +558,8 @@ If you want to limit the router scope to a set of entry points, set the entry po
[tcp.routers.Router-1.tls]
```
```yaml tab="YAML"
## Static configuration ##
entryPoints:
web:
# ...
web-secure:
# ...
other:
# ...
## Dynamic configuration ##
```yaml tab="File (YAML)"
## Dynamic configuration
tcp:
routers:
@ -534,57 +571,103 @@ If you want to limit the router scope to a set of entry points, set the entry po
tls: {}
```
??? example "Listens to Specific Entry Points"
**Static Configuration**
```toml tab="TOML"
## Static configuration ##
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
# ...
[entryPoints.web-secure]
# ...
address = ":80"
[entryPoints.websecure]
address = ":443"
[entryPoints.other]
# ...
## Dynamic configuration ##
address = ":9090"
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
other:
address: ":9090"
```
```bash tab="CLI"
## Static configuration
--entrypoints.web.address=":80"
--entrypoints.websecure.address=":443"
--entrypoints.other.address=":9090"
```
??? example "Listens to Specific Entry Points"
**Dynamic Configuration**
```toml tab="File (TOML)"
## Dynamic configuration
[tcp.routers]
[tcp.routers.Router-1]
# won't listen to entry point web
entryPoints = ["web-secure", "other"]
entryPoints = ["websecure", "other"]
rule = "HostSNI(`traefik.io`)"
service = "service-1"
# will route TLS requests (and ignore non tls requests)
[tcp.routers.Router-1.tls]
```
```yaml tab="YAML"
## Static configuration ##
entryPoints:
web:
# ...
web-secure:
# ...
other:
# ...
## Dynamic configuration ##
```yaml tab="File (YAML)"
## Dynamic configuration
tcp:
routers:
Router-1:
# won't listen to entry point web
entryPoints:
- "web-secure"
- "other"
- "websecure"
- "other"
rule: "HostSNI(`traefik.io`)"
service: "service-1"
# will route TLS requests (and ignore non tls requests)
tls: {}
```
**Static Configuration**
```toml tab="File (TOML)"
## Static configuration
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.websecure]
address = ":443"
[entryPoints.other]
address = ":9090"
```
```yaml tab="File (YAML)"
## Static configuration
entryPoints:
web:
address: ":80"
websecure:
address: ":443"
other:
address: ":9090"
```
```bash tab="CLI"
## Static configuration
--entrypoints.web.address=":80"
--entrypoints.websecure.address=":443"
--entrypoints.other.address=":9090"
```
### Rule
| Rule | Description |
@ -602,20 +685,20 @@ If you want to limit the router scope to a set of entry points, set the entry po
You must attach a TCP [service](../services/index.md) per TCP router.
Services are the target for the router.
!!! note "TCP Only"
TCP routers can only target TCP services (not HTTP services).
!!! important "TCP routers can only target TCP services (not HTTP services)."
### TLS
#### General
When a TLS section is specified, it instructs Traefik that the current router is dedicated to TLS requests only (and that the router should ignore non-TLS requests).
By default, Traefik will terminate the SSL connections (meaning that it will send decrypted data to the services), but Traefik can be configured in order to let the requests pass through (keeping the data encrypted), and be forwarded to the service "as is".
??? example "Configuring TLS Termination"
```toml tab="TOML"
```toml tab="File (TOML)"
## Dynamic configuration
[tcp.routers]
[tcp.routers.Router-1]
rule = "HostSNI(`foo-domain`)"
@ -624,7 +707,8 @@ Services are the target for the router.
[tcp.routers.Router-1.tls]
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
## Dynamic configuration
tcp:
routers:
Router-1:
@ -636,7 +720,8 @@ Services are the target for the router.
??? example "Configuring passthrough"
```toml tab="TOML"
```toml tab="File (TOML)"
## Dynamic configuration
[tcp.routers]
[tcp.routers.Router-1]
rule = "HostSNI(`foo-domain`)"
@ -645,7 +730,8 @@ Services are the target for the router.
passthrough = true
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
## Dynamic configuration
tcp:
routers:
Router-1:
@ -655,7 +741,7 @@ Services are the target for the router.
passthrough: true
```
!!! note "TLS & ACME"
!!! info "TLS & ACME"
In the current version, with [ACME](../../https/acme.md) enabled, automatic certificate generation will apply to every router declaring a TLS section.
@ -664,9 +750,10 @@ Services are the target for the router.
The `options` field enables fine-grained control of the TLS parameters.
It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied only if a `HostSNI` rule is defined.
??? example "Configuring the tls options"
!!! example "Configuring the tls options"
```toml tab="TOML"
```toml tab="File (TOML)"
## Dynamic configuration
[tcp.routers]
[tcp.routers.Router-1]
rule = "HostSNI(`foo-domain`)"
@ -684,7 +771,8 @@ It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied
]
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
## Dynamic configuration
tcp:
routers:
Router-1:
@ -699,15 +787,16 @@ It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied
foo:
minVersion: VersionTLS12
cipherSuites:
- "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
- "TLS_RSA_WITH_AES_256_GCM_SHA384"
- "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
- "TLS_RSA_WITH_AES_256_GCM_SHA384"
```
#### `certResolver`
See [`certResolver` for HTTP router](./index.md#certresolver) for more information.
```toml tab="TOML"
```toml tab="File (TOML)"
## Dynamic configuration
[tcp.routers]
[tcp.routers.routerfoo]
rule = "HostSNI(`snitest.com`)"
@ -715,7 +804,8 @@ See [`certResolver` for HTTP router](./index.md#certresolver) for more informati
certResolver = "foo"
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
## Dynamic configuration
tcp:
routers:
routerfoo:
@ -728,7 +818,8 @@ tcp:
See [`domains` for HTTP router](./index.md#domains) for more information.
```toml tab="TOML"
```toml tab="File (TOML)"
## Dynamic configuration
[tcp.routers]
[tcp.routers.routerbar]
rule = "HostSNI(`snitest.com`)"
@ -736,10 +827,11 @@ See [`domains` for HTTP router](./index.md#domains) for more information.
certResolver = "bar"
[[tcp.routers.routerbar.tls.domains]]
main = "snitest.com"
sans = "*.snitest.com"
sans = ["*.snitest.com"]
```
```yaml tab="YAML"
```yaml tab="File (YAML)"
## Dynamic configuration
tcp:
routers:
routerbar:
@ -747,6 +839,6 @@ tcp:
tls:
certResolver: "bar"
domains:
- main: "snitest.com"
sans: "*.snitest.com"
- main: "snitest.com"
sans: "*.snitest.com"
```

56
docs/content/routing/services/index.md
View file

@ -12,6 +12,7 @@ The `Services` are responsible for configuring how to reach the actual services
??? example "Declaring an HTTP Service with Two Servers -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.my-service.loadBalancer]
@ -22,6 +23,7 @@ The `Services` are responsible for configuring how to reach the actual services
```
```yaml tab="YAML"
## Dynamic configuration
http:
services:
my-service:
@ -34,6 +36,7 @@ The `Services` are responsible for configuring how to reach the actual services
??? example "Declaring a TCP Service with Two Servers -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[tcp.services]
[tcp.services.my-service.loadBalancer]
[[tcp.services.my-service.loadBalancer.servers]]
@ -61,6 +64,7 @@ The load balancers are able to load balance the requests between multiple instan
??? example "Declaring a Service with Two Servers (with Load Balancing) -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.my-service.loadBalancer]
@ -85,14 +89,15 @@ The load balancers are able to load balance the requests between multiple instan
Servers declare a single instance of your program.
The `url` option point to a specific instance.
!!! note
Paths in the servers' `url` have no effet.
!!! info ""
Paths in the servers' `url` have no effect.
If you want the requests to be sent to a specific path on your servers,
configure your [`routers`](../routers/index.md) to use a corresponding [middleware](../../middlewares/overview.md) (e.g. the [AddPrefix](../../middlewares/addprefix.md) or [ReplacePath](../../middlewares/replacepath.md)) middlewares.
??? example "A Service with One Server -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.my-service.loadBalancer]
[[http.services.my-service.loadBalancer.servers]]
@ -100,6 +105,7 @@ The `url` option point to a specific instance.
```
```yaml tab="YAML"
## Dynamic configuration
http:
services:
my-service:
@ -115,6 +121,7 @@ For now, only round robin load balancing is supported:
??? example "Load Balancing -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.my-service.loadBalancer]
[[http.services.my-service.loadBalancer.servers]]
@ -124,6 +131,7 @@ For now, only round robin load balancing is supported:
```
```yaml tab="YAML"
## Dynamic configuration
http:
services:
my-service:
@ -138,27 +146,29 @@ For now, only round robin load balancing is supported:
When sticky sessions are enabled, a cookie is set on the initial request to track which server handles the first response.
On subsequent requests, the client is forwarded to the same server.
!!! note "Stickiness & Unhealthy Servers"
!!! info "Stickiness & Unhealthy Servers"
If the server specified in the cookie becomes unhealthy, the request will be forwarded to a new server (and the cookie will keep track of the new server).
!!! note "Cookie Name"
!!! info "Cookie Name"
The default cookie name is an abbreviation of a sha1 (ex: `_1d52e`).
!!! note "Secure & HTTPOnly flags"
!!! info "Secure & HTTPOnly flags"
By default, the affinity cookie is created without those flags. One however can change that through configuration.
??? example "Adding Stickiness"
??? example "Adding Stickiness -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.my-service]
[http.services.my-service.loadBalancer.sticky.cookie]
```
```yaml tab="YAML"
## Dynamic configuration
http:
services:
my-service:
@ -167,9 +177,10 @@ On subsequent requests, the client is forwarded to the same server.
cookie: {}
```
??? example "Adding Stickiness with custom Options"
??? example "Adding Stickiness with custom Options -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.my-service]
[http.services.my-service.loadBalancer.sticky.cookie]
@ -179,6 +190,7 @@ On subsequent requests, the client is forwarded to the same server.
```
```yaml tab="YAML"
## Dynamic configuration
http:
services:
my-service:
@ -205,12 +217,12 @@ Below are the available options for the health check mechanism:
- `timeout` defines the maximum duration Traefik will wait for a health check request before considering the server failed (unhealthy).
- `headers` defines custom headers to be sent to the health check endpoint.
!!! note "Interval & Timeout Format"
!!! info "Interval & Timeout Format"
Interval and timeout are to be given in a format understood by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration).
The interval must be greater than the timeout. If configuration doesn't reflect this, the interval will be set to timeout + 1 second.
!!! note "Recovering Servers"
!!! info "Recovering Servers"
Traefik keeps monitoring the health of unhealthy servers.
If a server has recovered (returning `2xx` -> `3xx` responses again), it will be added back to the load balacer rotation pool.
@ -218,6 +230,7 @@ Below are the available options for the health check mechanism:
??? example "Custom Interval & Timeout -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.servicess.Service-1]
[http.services.Service-1.loadBalancer.healthCheck]
@ -227,6 +240,7 @@ Below are the available options for the health check mechanism:
```
```yaml tab="YAML"
## Dynamic configuration
http:
servicess:
Service-1:
@ -240,6 +254,7 @@ Below are the available options for the health check mechanism:
??? example "Custom Port -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.Service-1]
[http.services.Service-1.loadBalancer.healthCheck]
@ -248,6 +263,7 @@ Below are the available options for the health check mechanism:
```
```yaml tab="YAML"
## Dynamic configuration
http:
services:
Service-1:
@ -260,6 +276,7 @@ Below are the available options for the health check mechanism:
??? example "Custom Scheme -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.Service-1]
[http.services.Service-1.loadBalancer.healthCheck]
@ -268,6 +285,7 @@ Below are the available options for the health check mechanism:
```
```yaml tab="YAML"
## Dynamic configuration
http:
services:
Service-1:
@ -280,6 +298,7 @@ Below are the available options for the health check mechanism:
??? example "Additional HTTP Headers -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.Service-1]
[http.services.Service-1.loadBalancer.healthCheck]
@ -291,6 +310,7 @@ Below are the available options for the health check mechanism:
```
```yaml tab="YAML"
## Dynamic configuration
http:
services:
Service-1:
@ -308,9 +328,10 @@ The WRR is able to load balance the requests between multiple services based on
This strategy is only available to load balance between [services](./index.md) and not between [servers](./index.md#servers).
This strategy can be defined only with [File](../../providers/file.md).
!!! info "This strategy can be defined only with [File](../../providers/file.md)."
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.app]
[[http.services.app.weighted.services]]
@ -332,6 +353,7 @@ This strategy can be defined only with [File](../../providers/file.md).
```
```yaml tab="YAML"
## Dynamic configuration
http:
services:
app:
@ -357,9 +379,10 @@ http:
The mirroring is able to mirror requests sent to a service to other services.
This strategy can be defined only with [File](../../providers/file.md).
!!! info "This strategy can be defined only with [File](../../providers/file.md)."
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.mirrored-api]
[http.services.mirrored-api.mirroring]
@ -380,6 +403,7 @@ This strategy can be defined only with [File](../../providers/file.md).
```
```yaml tab="YAML"
## Dynamic configuration
http:
services:
mirrored-api:
@ -416,6 +440,7 @@ The servers load balancer is in charge of balancing the requests between the ser
??? example "Declaring a Service with Two Servers -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[tcp.services]
[tcp.services.my-service.loadBalancer]
[[tcp.services.my-service.loadBalancer.servers]]
@ -425,6 +450,7 @@ The servers load balancer is in charge of balancing the requests between the ser
```
```yaml tab="YAML"
## Dynamic configuration
tcp:
services:
my-service:
@ -442,6 +468,7 @@ The `address` option (IP:Port) point to a specific instance.
??? example "A Service with One Server -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[tcp.services]
[tcp.services.my-service.loadBalancer]
[[tcp.services.my-service.loadBalancer.servers]]
@ -449,6 +476,7 @@ The `address` option (IP:Port) point to a specific instance.
```
```yaml tab="YAML"
## Dynamic configuration
tcp:
services:
my-service:
@ -474,6 +502,7 @@ A negative value means an infinite deadline (i.e. the connection is never fully
??? example "A Service with a termination delay -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
## Dynamic configuration
[tcp.services]
[tcp.services.my-service.loadBalancer]
[[tcp.services.my-service.loadBalancer]]
@ -481,6 +510,7 @@ A negative value means an infinite deadline (i.e. the connection is never fully
```
```yaml tab="YAML"
## Dynamic configuration
tcp:
services:
my-service:
@ -488,7 +518,7 @@ A negative value means an infinite deadline (i.e. the connection is never fully
terminationDelay: 200
```
### Weighted
### Weighted Round Robin
The Weighted Round Robin (alias `WRR`) load-balancer of services is in charge of balancing the requests between multiple services based on provided weights.
@ -497,6 +527,7 @@ This strategy is only available to load balance between [services](./index.md) a
This strategy can only be defined with [File](../../providers/file.md).
```toml tab="TOML"
## Dynamic configuration
[tcp.services]
[tcp.services.app]
[[tcp.services.app.weighted.services]]
@ -518,6 +549,7 @@ This strategy can only be defined with [File](../../providers/file.md).
```
```yaml tab="YAML"
## Dynamic configuration
tcp:
services:
app:

2
docs/content/user-guides/crd-acme/index.md
View file

@ -18,7 +18,7 @@ In the following, the Kubernetes resources defined in YAML configuration files c
!!! important "Kubectl Version"
With the `rancher/k3s` version used in this guide (`0.8.0`), the kubectl version needs to be >= `0.11`.
With the `rancher/k3s` version used in this guide (`0.8.0`), the kubectl version needs to be >= `1.11`.
## k3s Docker-compose Configuration

2
docs/content/user-guides/grpc.md
View file

@ -143,7 +143,7 @@ entryPoints:
serversTransport:
# For secure connection on backend.local
rootCAs:
- ./backend.cert
- ./backend.cert
providers:
file:

7
docs/mkdocs.yml
View file

@ -82,9 +82,14 @@ nav:
- 'Marathon': 'providers/marathon.md'
- 'Routing & Load Balancing':
- 'Overview': 'routing/overview.md'
- 'Entrypoints': 'routing/entrypoints.md'
- 'EntryPoints': 'routing/entrypoints.md'
- 'Routers': 'routing/routers/index.md'
- 'Services': 'routing/services/index.md'
- 'Providers':
- 'Docker': 'routing/providers/docker.md'
- 'Kubernetes IngressRoute': 'routing/providers/kubernetes-crd.md'
- 'Rancher': 'routing/providers/rancher.md'
- 'Marathon': 'routing/providers/marathon.md'
- 'HTTPS & TLS':
- 'Overview': 'https/overview.md'
- 'TLS': 'https/tls.md'

2
pkg/config/parser/labels_decode.go
View file

@ -65,7 +65,7 @@ func decodeToNode(root *Node, path []string, value string) {
func containsNode(nodes []*Node, name string) *Node {
for _, n := range nodes {
if name == n.Name {
if strings.EqualFold(name, n.Name) {
return n
}
}

16
pkg/config/parser/labels_decode_test.go
View file

@ -117,6 +117,22 @@ func TestDecodeToNode(t *testing.T) {
},
}},
},
{
desc: "several entries, level 2, case insensitive",
in: map[string]string{
"traefik.foo.aaa": "bar",
"traefik.Foo.bbb": "bur",
},
expected: expected{node: &Node{
Name: "traefik",
Children: []*Node{
{Name: "Foo", Children: []*Node{
{Name: "bbb", Value: "bur"},
{Name: "aaa", Value: "bar"},
}},
},
}},
},
{
desc: "several entries, level 2, 3 children",
in: map[string]string{

2
pkg/server/service/service.go
View file

@ -310,7 +310,7 @@ func (m *Manager) getLoadBalancer(ctx context.Context, serviceName string, servi
return nil, fmt.Errorf("error configuring load balancer for service %s: %v", serviceName, err)
}
return lb, nil
return lbsu, nil
}
func (m *Manager) upsertServers(ctx context.Context, lb healthcheck.BalancerHandler, servers []dynamic.Server) error {

2
webui/src/components/_commons/PanelMiddlewares.vue
View file

@ -3,7 +3,7 @@
<q-scroll-area v-if="data && data.length" :thumb-style="appThumbStyle" style="height:100%;">
<div v-for="(middleware, index) in data" :key="index">
<q-card-section v-if="!isDense" class="app-title">
<div class="app-title-label text-capitalize">{{ middleware.name }}</div>
<div class="app-title-label">{{ middleware.name }}</div>
</q-card-section>
<!-- COMMON FIELDS -->
<q-card-section>