@ -4,17 +4,17 @@ ___
# < a id = "top" > < / a > Documentation
* [Basics ](#basics )
* [Global configuration ](#global )
* [File backend ](#file )
* [API backend ](#api )
* [Docker backend ](#docker )
* [Mesos/Marathon backend ](#marathon )
* [Consul backend ](#consul )
* [Etcd backend ](#etcd )
* [Zookeeper backend ](#zk )
* [Boltdb backend ](#boltdb )
* [Benchmarks ](#benchmarks )
- [Basics ](#basics )
- [Global configuration ](#global )
- [File backend ](#file )
- [API backend ](#api )
- [Docker backend ](#docker )
- [Mesos/Marathon backend ](#marathon )
- [Consul backend ](#consul )
- [Etcd backend ](#etcd )
- [Zookeeper backend ](#zk )
- [Boltdb backend ](#boltdb )
- [Benchmarks ](#benchmarks )
## < a id = "basics" > < / a > Basics
@ -29,12 +29,12 @@ Basically, Træfɪ k is a http router, which sends traffic from frontends to http
Frontends can be defined using the following rules:
* `Headers` : Headers adds a matcher for request header values. It accepts a sequence of key/value pairs to be matched. For example: `application/json`
* `HeadersRegexp` : Regular expressions can be used with headers as well. It accepts a sequence of key/value pairs, where the value has regex support. For example: `application/(text|json)`
* `Host` : Host adds a matcher for the URL host. It accepts a template with zero or more URL variables enclosed by `{}` . Variables can define an optional regexp pattern to be matched: `www.traefik.io` , `{subdomain:[a-z]+}.traefik.io`
* `Methods` : Methods adds a matcher for HTTP methods. It accepts a sequence of one or more methods to be matched, e.g.: `GET` , `POST` , `PUT`
* `Path` : Path adds a matcher for the URL path. It accepts a template with zero or more URL variables enclosed by `{}` . The template must start with a `/` . For exemple `/products/` `/articles/{category}/{id:[0-9]+}`
* `PathPrefix` : PathPrefix adds a matcher for the URL path prefix. This matches if the given template is a prefix of the full URL path.
- `Headers` : Headers adds a matcher for request header values. It accepts a sequence of key/value pairs to be matched. For example: `application/json`
- `HeadersRegexp` : Regular expressions can be used with headers as well. It accepts a sequence of key/value pairs, where the value has regex support. For example: `application/(text|json)`
- `Host` : Host adds a matcher for the URL host. It accepts a template with zero or more URL variables enclosed by `{}` . Variables can define an optional regexp pattern to be matched: `www.traefik.io` , `{subdomain:[a-z]+}.traefik.io`
- `Methods` : Methods adds a matcher for HTTP methods. It accepts a sequence of one or more methods to be matched, e.g.: `GET` , `POST` , `PUT`
- `Path` : Path adds a matcher for the URL path. It accepts a template with zero or more URL variables enclosed by `{}` . The template must start with a `/` . For exemple `/products/` `/articles/{category}/{id:[0-9]+}`
- `PathPrefix` : PathPrefix adds a matcher for the URL path prefix. This matches if the given template is a prefix of the full URL path.
A frontend is a set of rules that forwards the incoming http traffic to a backend.
@ -44,19 +44,19 @@ Frontends can be defined using the following rules:
A backend is responsible to load-balance the traffic coming from one or more frontends to a set of http servers.
Various methods of load-balancing is supported:
* `wrr` : Weighted Round Robin
* `drr` : Dynamic Round Robin: increases weights on servers that perform better than others. It also rolls back to original weights if the servers have changed.
- `wrr` : Weighted Round Robin
- `drr` : Dynamic Round Robin: increases weights on servers that perform better than others. It also rolls back to original weights if the servers have changed.
A circuit breaker can also be applied to a backend, preventing high loads on failing servers.
It can be configured using:
* Methods: `LatencyAtQuantileMS` , `NetworkErrorRatio` , `ResponseCodeRatio`
* Operators: `AND` , `OR` , `EQ` , `NEQ` , `LT` , `LE` , `GT` , `GE`
- Methods: `LatencyAtQuantileMS` , `NetworkErrorRatio` , `ResponseCodeRatio`
- Operators: `AND` , `OR` , `EQ` , `NEQ` , `LT` , `LE` , `GT` , `GE`
For example:
* `NetworkErrorRatio() > 0.5`
* `LatencyAtQuantileMS(50.0) > 50`
* `ResponseCodeRatio(500, 600, 0, 600) > 0.5`
- `NetworkErrorRatio() > 0.5`
- `LatencyAtQuantileMS(50.0) > 50`
- `ResponseCodeRatio(500, 600, 0, 600) > 0.5`
## < a id = "global" > < / a > Global configuration
@ -114,7 +114,7 @@ For example:
Like any other reverse proxy, Træfɪ k can be configured with a file. You have two choices:
* simply add your configuration at the end of the global configuration file `traefik.toml` :
- simply add your configuration at the end of the global configuration file `traefik.toml` :
```toml
# traefik.toml
@ -158,7 +158,7 @@ logLevel = "DEBUG"
value = "/test"
```
* or put your rules in a separate file, for example `rules.tml` :
- or put your rules in a separate file, for example `rules.tml` :
```toml
# traefik.toml
@ -230,12 +230,12 @@ address = ":8080"
# KeyFile = "traefik.key"
```
* `/` : provides a simple HTML frontend of Træfik
- `/` : provides a simple HTML frontend of Træfik
![Web UI Providers ](img/web.frontend.png )
![Web UI Health ](img/traefik-health.png )
* `/health` : `GET` json metrics
- `/health` : `GET` json metrics
```sh
$ curl -s "http://localhost:8080/health" | jq .
@ -275,64 +275,63 @@ $ curl -s "http://localhost:8080/health" | jq .
}
```
* `/api` : `GET` configuration for all providers
- `/api` : `GET` configuration for all providers
```sh
$ curl -s "http://localhost:8080/api" | jq .
{
"file": {
"F rontends": {
"f rontends": {
"frontend2": {
"R outes": {
"r outes": {
"test_2": {
"V alue": "/test",
"R ule": "Path"
"v alue": "/test",
"r ule": "Path"
}
},
"B ackend": "backend1"
"b ackend": "backend1"
},
"frontend1": {
"R outes": {
"r outes": {
"test_1": {
"V alue": "test.localhost",
"R ule": "Host"
"v alue": "test.localhost",
"r ule": "Host"
}
},
"B ackend": "backend2"
"b ackend": "backend2"
}
},
"B ackends": {
"b ackends": {
"backend2": {
"L oadBalancer": {
"M ethod": "drr"
"l oadBalancer": {
"m ethod": "drr"
},
"CircuitBreaker": null,
"Servers": {
"servers": {
"server2": {
"W eight": 2,
"w eight": 2,
"URL": "http://172.17.0.5:80"
},
"server1": {
"W eight": 1,
"URL ": "http://172.17.0.4:80"
"w eight": 1,
"url ": "http://172.17.0.4:80"
}
}
},
"backend1": {
"L oadBalancer": {
"M ethod": "wrr"
"l oadBalancer": {
"m ethod": "wrr"
},
"C ircuitBreaker": {
"E xpression": "NetworkErrorRatio() > 0.5"
"c ircuitBreaker": {
"e xpression": "NetworkErrorRatio() > 0.5"
},
"S ervers": {
"s ervers": {
"server2": {
"W eight": 1,
"URL ": "http://172.17.0.3:80"
"w eight": 1,
"url ": "http://172.17.0.3:80"
},
"server1": {
"W eight": 10,
"URL ": "http://172.17.0.2:80"
"w eight": 10,
"url ": "http://172.17.0.2:80"
}
}
}
@ -394,14 +393,13 @@ watch = true
# filename = "docker.tmpl"
```
Labels can be used on containers to override default behaviour:
* `traefik.backend=foo` : assign the container to `foo` backend
* `traefik.port=80` : register this port. Useful when the container exposes multiples ports.
* `traefik.weight=10` : assign this weight to the container
* `traefik.enable=false` : disable this container in Træfɪ k
* `traefik.host=bar` : override the default routing from {containerName}.{domain} to bar.{domain}
- `traefik.backend=foo` : assign the container to `foo` backend
- `traefik.port=80` : register this port. Useful when the container exposes multiples ports.
- `traefik.weight=10` : assign this weight to the container
- `traefik.enable=false` : disable this container in Træfɪ k
- `traefik.host=bar` : override the default routing from ` {containerName}.{domain}` to ` bar.{domain}`
* `traefik.domain=traefik.localhost` : override the default domain
## < a id = "marathon" > < / a > Marathon backend
@ -456,12 +454,12 @@ domain = "marathon.localhost"
Labels can be used on containers to override default behaviour:
* `traefik.backend=foo` : assign the application to `foo` backend
* `traefik.port=80` : register this port. Useful when the application exposes multiples ports.
* `traefik.weight=10` : assign this weight to the application
* `traefik.enable=false` : disable this application in Træfɪ k
* `traefik.host=bar` : override the default routing from {appName}.{domain} to bar.{domain}
* `traefik.prefixes=pf1,pf2` : use PathPrefix(es) instead of hostname for routing, use filename="providerTemplates/marathon-prefix.tmpl" with this option
- `traefik.backend=foo` : assign the application to `foo` backend
- `traefik.port=80` : register this port. Useful when the application exposes multiples ports.
- `traefik.weight=10` : assign this weight to the application
- `traefik.enable=false` : disable this application in Træfɪ k
- `traefik.host=bar` : override the default routing from ` {appName}.{domain}` to ` bar.{domain}`
- `traefik.prefixes=pf1,pf2` : use `PathPrefix(es)` instead of hostname for routing, use ` filename="providerTemplates/marathon-prefix.tmpl"` with this option
* `traefik.domain=traefik.localhost` : override the default domain
## < a id = "consul" > < / a > Consul backend
@ -508,39 +506,39 @@ The Keys-Values structure should look (using `prefix = "/traefik"`):
- backend 1
| Key | Value |
| ------------- | ----------- |
| /traefik/backends/backend1/circuitbreaker/expression | `NetworkErrorRatio() > 0.5` |
| /traefik/backends/backend1/servers/server1/url | `http://172.17.0.2:80` |
| /traefik/backends/backend1/servers/server1/weight | `10` |
| /traefik/backends/backend1/servers/server2/url | `http://172.17.0.3:80` |
| /traefik/backends/backend1/servers/server2/weight | `1` |
| Key | Value |
|--------------------------------------------------------|----------------------------- |
| ` /traefik/backends/backend1/circuitbreaker/expression` | `NetworkErrorRatio() > 0.5` |
| ` /traefik/backends/backend1/servers/server1/url` | `http://172.17.0.2:80` |
| ` /traefik/backends/backend1/servers/server1/weight` | `10` |
| ` /traefik/backends/backend1/servers/server2/url` | `http://172.17.0.3:80` |
| ` /traefik/backends/backend1/servers/server2/weight` | `1` |
- backend 2
| Key | Value |
| ------------- | ----------- |
| /traefik/backends/backend2/loadbalancer/method | `drr` |
| /traefik/backends/backend2/servers/server1/url | `http://172.17.0.4:80` |
| /traefik/backends/backend2/servers/server1/weight | `1` |
| /traefik/backends/backend2/servers/server2/url | `http://172.17.0.5:80` |
| /traefik/backends/backend2/servers/server2/weight | `2` |
| Key | Value |
|-----------------------------------------------------|------------------------ |
| ` /traefik/backends/backend2/loadbalancer/method` | `drr` |
| ` /traefik/backends/backend2/servers/server1/url` | `http://172.17.0.4:80` |
| ` /traefik/backends/backend2/servers/server1/weight` | `1` |
| ` /traefik/backends/backend2/servers/server2/url` | `http://172.17.0.5:80` |
| ` /traefik/backends/backend2/servers/server2/weight` | `2` |
- frontend 1
| Key | Value |
| ------------- | ----------- |
| /traefik/frontends/frontend1/backend | `backend2` |
| /traefik/frontends/frontend1/routes/test_1/rule | `Host` |
| /traefik/frontends/frontend1/routes/test_1/value | `test.localhost` |
| Key | Value |
|----------------------------------------------------|------------------ |
| ` /traefik/frontends/frontend1/backend` | `backend2` |
| ` /traefik/frontends/frontend1/routes/test_1/rule` | `Host` |
| ` /traefik/frontends/frontend1/routes/test_1/value` | `test.localhost` |
- frontend 2
| Key | Value |
| ------------- | ----------- |
| /traefik/frontends/frontend2/backend | `backend1` |
| /traefik/frontends/frontend2/routes/test_2/rule | `Path` |
| /traefik/frontends/frontend2/routes/test_2/value | `/test` |
| Key | Value |
|----------------------------------------------------|------------ |
| ` /traefik/frontends/frontend2/backend` | `backend1` |
| ` /traefik/frontends/frontend2/routes/test_2/rule` | `Path` |
| ` /traefik/frontends/frontend2/routes/test_2/value` | `/test` |
## < a id = "etcd" > < / a > Etcd backend
@ -587,39 +585,39 @@ The Keys-Values structure should look (using `prefix = "/traefik"`):
- backend 1
| Key | Value |
| ------------- | ----------- |
| /traefik/backends/backend1/circuitbreaker/expression | `NetworkErrorRatio() > 0.5` |
| /traefik/backends/backend1/servers/server1/url | `http://172.17.0.2:80` |
| /traefik/backends/backend1/servers/server1/weight | `10` |
| /traefik/backends/backend1/servers/server2/url | `http://172.17.0.3:80` |
| /traefik/backends/backend1/servers/server2/weight | `1` |
| Key | Value |
|--------------------------------------------------------|----------------------------- |
| ` /traefik/backends/backend1/circuitbreaker/expression` | `NetworkErrorRatio() > 0.5` |
| ` /traefik/backends/backend1/servers/server1/url` | `http://172.17.0.2:80` |
| ` /traefik/backends/backend1/servers/server1/weight` | `10` |
| ` /traefik/backends/backend1/servers/server2/url` | `http://172.17.0.3:80` |
| ` /traefik/backends/backend1/servers/server2/weight` | `1` |
- backend 2
| Key | Value |
| ------------- | ----------- |
| /traefik/backends/backend2/loadbalancer/method | `drr` |
| /traefik/backends/backend2/servers/server1/url | `http://172.17.0.4:80` |
| /traefik/backends/backend2/servers/server1/weight | `1` |
| /traefik/backends/backend2/servers/server2/url | `http://172.17.0.5:80` |
| /traefik/backends/backend2/servers/server2/weight | `2` |
| Key | Value |
|-----------------------------------------------------|------------------------ |
| ` /traefik/backends/backend2/loadbalancer/method` | `drr` |
| ` /traefik/backends/backend2/servers/server1/url` | `http://172.17.0.4:80` |
| ` /traefik/backends/backend2/servers/server1/weight` | `1` |
| ` /traefik/backends/backend2/servers/server2/url` | `http://172.17.0.5:80` |
| ` /traefik/backends/backend2/servers/server2/weight` | `2` |
- frontend 1
| Key | Value |
| ------------- | ----------- |
| /traefik/frontends/frontend1/backend | `backend2` |
| /traefik/frontends/frontend1/routes/test_1/rule | `Host` |
| /traefik/frontends/frontend1/routes/test_1/value | `test.localhost` |
| Key | Value |
|----------------------------------------------------|------------------ |
| ` /traefik/frontends/frontend1/backend` | `backend2` |
| ` /traefik/frontends/frontend1/routes/test_1/rule` | `Host` |
| ` /traefik/frontends/frontend1/routes/test_1/value` | `test.localhost` |
- frontend 2
| Key | Value |
| ------------- | ----------- |
| /traefik/frontends/frontend2/backend | `backend1` |
| /traefik/frontends/frontend2/routes/test_2/rule | `Path` |
| /traefik/frontends/frontend2/routes/test_2/value | `/test` |
| Key | Value |
|----------------------------------------------------|------------ |
| ` /traefik/frontends/frontend2/backend` | `backend1` |
| ` /traefik/frontends/frontend2/routes/test_2/rule` | `Path` |
| ` /traefik/frontends/frontend2/routes/test_2/value` | `/test` |
## < a id = "zk" > < / a > Zookeeper backend
@ -665,39 +663,39 @@ The Keys-Values structure should look (using `prefix = "/traefik"`):
- backend 1
| Key | Value |
| ------------- | ----------- |
| /traefik/backends/backend1/circuitbreaker/expression | `NetworkErrorRatio() > 0.5` |
| /traefik/backends/backend1/servers/server1/url | `http://172.17.0.2:80` |
| /traefik/backends/backend1/servers/server1/weight | `10` |
| /traefik/backends/backend1/servers/server2/url | `http://172.17.0.3:80` |
| /traefik/backends/backend1/servers/server2/weight | `1` |
| Key | Value |
|--------------------------------------------------------|----------------------------- |
| ` /traefik/backends/backend1/circuitbreaker/expression` | `NetworkErrorRatio() > 0.5` |
| ` /traefik/backends/backend1/servers/server1/url` | `http://172.17.0.2:80` |
| ` /traefik/backends/backend1/servers/server1/weight` | `10` |
| ` /traefik/backends/backend1/servers/server2/url` | `http://172.17.0.3:80` |
| ` /traefik/backends/backend1/servers/server2/weight` | `1` |
- backend 2
| Key | Value |
| ------------- | ----------- |
| /traefik/backends/backend2/loadbalancer/method | `drr` |
| /traefik/backends/backend2/servers/server1/url | `http://172.17.0.4:80` |
| /traefik/backends/backend2/servers/server1/weight | `1` |
| /traefik/backends/backend2/servers/server2/url | `http://172.17.0.5:80` |
| /traefik/backends/backend2/servers/server2/weight | `2` |
| Key | Value |
|-----------------------------------------------------|------------------------ |
| ` /traefik/backends/backend2/loadbalancer/method` | `drr` |
| ` /traefik/backends/backend2/servers/server1/url` | `http://172.17.0.4:80` |
| ` /traefik/backends/backend2/servers/server1/weight` | `1` |
| ` /traefik/backends/backend2/servers/server2/url` | `http://172.17.0.5:80` |
| ` /traefik/backends/backend2/servers/server2/weight` | `2` |
- frontend 1
| Key | Value |
| ------------- | ----------- |
| /traefik/frontends/frontend1/backend | `backend2` |
| /traefik/frontends/frontend1/routes/test_1/rule | `Host` |
| /traefik/frontends/frontend1/routes/test_1/value | `test.localhost` |
| Key | Value |
|---------------------------------------------------|------------------ |
| `/traefik/frontends/frontend1/backend | ` backend2` |
| `/traefik/frontends/frontend1/routes/test_1/rule | ` Host` |
| ` /traefik/frontends/frontend1/routes/test_1/value | ` test.localhost` |
- frontend 2
| Key | Value |
| ------------- | ----------- |
| /traefik/frontends/frontend2/backend | `backend1` |
| /traefik/frontends/frontend2/routes/test_2/rule | `Path` |
| /traefik/frontends/frontend2/routes/test_2/value | `/test` |
| Key | Value |
|----------------------------------------------------|------------ |
| ` /traefik/frontends/frontend2/backend` | `backend1` |
| ` /traefik/frontends/frontend2/routes/test_2/rule` | `Path` |
| ` /traefik/frontends/frontend2/routes/test_2/value` | `/test` |
## < a id = "boltdb" > < / a > BoltDB backend
@ -745,7 +743,7 @@ Træfɪ k can be configured to use BoltDB as a backend configuration:
Here are some early Benchmarks between Nginx and Træfɪ k acting as simple load balancers between two servers.
* Nginx:
- Nginx:
```sh
$ docker run -d -e VIRTUAL_HOST=test1.localhost emilevauge/whoami
@ -805,10 +803,9 @@ Percentage of the requests served within a certain time (ms)
98% 12
99% 13
100% 36 (longest request)
```
* Træfɪ k:
- Træfɪ k:
```sh
$ docker run -d -l traefik.backend=test1 -l traefik.host=test1 emilevauge/whoami
@ -868,5 +865,4 @@ Percentage of the requests served within a certain time (ms)
98% 11
99% 13
100% 22 (longest request)
```