baalajimaestro/traefik
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity
traefik/docs/index.md
Emile Vauge 8393746e02 Fix benchmarks
2016-03-08 16:27:12 +01:00

40 KiB
Raw Blame History

Træfɪk

Documentation

Basics

Træfɪk is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease. It supports several backends (Docker 🐳, Mesos/Marathon, Consul, Etcd, Rest API, file...) to manage its configuration automatically and dynamically.

Basically, Træfɪk is a http router, which sends traffic from frontends to http backends, following rules you have configured.

Frontends

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]+}
  • PathStrip: Same as Path but strip the given prefix from the request URL's Path.
  • PathPrefix: PathPrefix adds a matcher for the URL path prefix. This matches if the given template is a prefix of the full URL path.
  • PathPrefixStrip: Same as PathPrefix but strip the given prefix from the request URL's Path.

A frontend is a set of rules that forwards the incoming http traffic to a backend. You can optionally enable passHostHeader to forward client Host header to the backend.

HTTP Backends

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.

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

For example:

  • NetworkErrorRatio() > 0.5
  • LatencyAtQuantileMS(50.0) > 50
  • ResponseCodeRatio(500, 600, 0, 600) > 0.5

Launch configuration

Træfɪk can be configured using a TOML file configuration, arguments, or both. By default, Træfɪk will try to find a traefik.toml in the following places:

  • /etc/traefik/
  • $HOME/.traefik/
  • . the working directory

You can override this by setting a configFile argument:

$ traefik --configFile=foo/bar/myconfigfile.toml

Træfɪk uses the following precedence order. Each item takes precedence over the item below it:

  • arguments
  • configuration file
  • default

It means that arguments overrides configuration file. Each argument is described in the help section:

$ traefik --help
traefik is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease.
Complete documentation is available at http://traefik.io

Usage:
  traefik [flags]
  traefik [command]

Available Commands:
  version     Print version

Flags:
      --accessLogsFile string                Access logs file (default "log/access.log")
      --boltdb                               Enable Boltdb backend
      --boltdb.endpoint string               Boltdb server endpoint (default "127.0.0.1:4001")
      --boltdb.filename string               Override default configuration template. For advanced users :)
      --boltdb.prefix string                 Prefix used for KV store (default "/traefik")
      --boltdb.watch                         Watch provider (default true)
  -c, --configFile string                    Configuration file to use (TOML, JSON, YAML, HCL).
      --consul                               Enable Consul backend
      --consul.endpoint string               Comma sepparated Consul server endpoints (default "127.0.0.1:8500")
      --consul.filename string               Override default configuration template. For advanced users :)
      --consul.prefix string                 Prefix used for KV store (default "/traefik")
      --consul.tls                           Enable Consul TLS support
      --consul.tls.ca string                 TLS CA
      --consul.tls.cert string               TLS cert
      --consul.tls.insecureSkipVerify        TLS insecure skip verify
      --consul.tls.key string                TLS key
      --consul.watch                         Watch provider (default true)
      --consulCatalog                        Enable Consul catalog backend
      --consulCatalog.domain string          Default domain used
      --consulCatalog.endpoint string        Consul server endpoint (default "127.0.0.1:8500")
      --defaultEntryPoints value             Entrypoints to be used by frontends that do not specify any entrypoint (default &main.DefaultEntryPoints(nil))
      --docker                               Enable Docker backend
      --docker.domain string                 Default domain used
      --docker.endpoint string               Docker server endpoint. Can be a tcp or a unix socket endpoint (default "unix:///var/run/docker.sock")
      --docker.filename string               Override default configuration template. For advanced users :)
      --docker.tls                           Enable Docker TLS support
      --docker.tls.ca string                 TLS CA
      --docker.tls.cert string               TLS cert
      --docker.tls.insecureSkipVerify        TLS insecure skip verify
      --docker.tls.key string                TLS key
      --docker.watch                         Watch provider (default true)
      --entryPoints value                    Entrypoints definition using format: --entryPoints='Name:http Address::8000 Redirect.EntryPoint:https' --entryPoints='Name:https Address::4442 TLS:tests/traefik.crt,tests/traefik.key'
      --etcd                                 Enable Etcd backend
      --etcd.endpoint string                 Comma sepparated Etcd server endpoints (default "127.0.0.1:4001")
      --etcd.filename string                 Override default configuration template. For advanced users :)
      --etcd.prefix string                   Prefix used for KV store (default "/traefik")
      --etcd.tls                             Enable Etcd TLS support
      --etcd.tls.ca string                   TLS CA
      --etcd.tls.cert string                 TLS cert
      --etcd.tls.insecureSkipVerify          TLS insecure skip verify
      --etcd.tls.key string                  TLS key
      --etcd.watch                           Watch provider (default true)
      --file                                 Enable File backend
      --file.filename string                 Override default configuration template. For advanced users :)
      --file.watch                           Watch provider (default true)
  -g, --graceTimeOut string                  Timeout in seconds. Duration to give active requests a chance to finish during hot-reloads (default "10")
  -l, --logLevel string                      Log level (default "ERROR")
      --marathon                             Enable Marathon backend
      --marathon.domain string               Default domain used
      --marathon.endpoint string             Marathon server endpoint. You can also specify multiple endpoint for Marathon (default "http://127.0.0.1:8080")
      --marathon.filename string             Override default configuration template. For advanced users :)
      --marathon.watch                       Watch provider (default true)
      --maxIdleConnsPerHost int              If non-zero, controls the maximum idle (keep-alive) to keep per-host.  If zero, DefaultMaxIdleConnsPerHost is used
      --providersThrottleDuration duration   Backends throttle duration: minimum duration between 2 events from providers before applying a new configuration. It avoids unnecessary reloads if multiples events are sent in a short amount of time. (default 2s)
      --traefikLogsFile string               Traefik logs file (default "log/traefik.log")
      --web                                  Enable Web backend
      --web.address string                   Web administration port (default ":8080")
      --web.cerFile string                   SSL certificate
      --web.keyFile string                   SSL certificate
      --web.readOnly                         Enable read only API
      --zookeeper                            Enable Zookeeper backend
      --zookeeper.endpoint string            Comma sepparated Zookeeper server endpoints (default "127.0.0.1:2181")
      --zookeeper.filename string            Override default configuration template. For advanced users :)
      --zookeeper.prefix string              Prefix used for KV store (default "/traefik")
      --zookeeper.watch                      Watch provider (default true)

Use "traefik [command] --help" for more information about a command.

Global configuration

# traefik.toml
################################################################
# Global configuration
################################################################

# Entrypoints definition
#
# Optional
# Default:
# [entryPoints]
#   [entryPoints.http]
#   address = ":80"
#
# To redirect an http entrypoint to an https entrypoint (with SNI support):
# [entryPoints]
#   [entryPoints.http]
#   address = ":80"
#     [entryPoints.http.redirect]
#       entryPoint = "https"
#   [entryPoints.https]
#   address = ":443"
#     [entryPoints.https.tls]
#       [[entryPoints.https.tls.certificates]]
#       CertFile = "integration/fixtures/https/snitest.com.cert"
#       KeyFile = "integration/fixtures/https/snitest.com.key"
#       [[entryPoints.https.tls.certificates]]
#       CertFile = "integration/fixtures/https/snitest.org.cert"
#       KeyFile = "integration/fixtures/https/snitest.org.key"
#
# To redirect an entrypoint rewriting the URL:
# [entryPoints]
#   [entryPoints.http]
#   address = ":80"
#     [entryPoints.http.redirect]
#       regex = "^http://localhost/(.*)"
#       replacement = "http://mydomain/$1"

# Entrypoints to be used by frontends that do not specify any entrypoint.
# Each frontend can specify its own entrypoints.
#
# Optional
# Default: ["http"]
#
# defaultEntryPoints = ["http", "https"]

# Timeout in seconds.
# Duration to give active requests a chance to finish during hot-reloads
#
# Optional
# Default: 10
#
# graceTimeOut = 10

# Traefik logs file
# If not defined, logs to stdout
#
# Optional
#
# traefikLogsFile = "log/traefik.log"

# Access logs file
#
# Optional
#
# accessLogsFile = "log/access.log"

# Log level
#
# Optional
# Default: "ERROR"
#
# logLevel = "ERROR"

# Backends throttle duration: minimum duration between 2 events from providers
# before applying a new configuration. It avoids unnecessary reloads if multiples events
# are sent in a short amount of time.
#
# Optional
# Default: "2s"
#
# ProvidersThrottleDuration = "5s"

# If non-zero, controls the maximum idle (keep-alive) to keep per-host.  If zero, DefaultMaxIdleConnsPerHost is used.
# If you encounter 'too many open files' errors, you can either change this value, or change `ulimit` value.
#
# Optional
# Default: http.DefaultMaxIdleConnsPerHost
#
# MaxIdleConnsPerHost = 200

File backend

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 :
# traefik.toml
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 = "integration/fixtures/https/snitest.com.cert"
      KeyFile = "integration/fixtures/https/snitest.com.key"
      [[entryPoints.https.tls.certificates]]
      CertFile = "integration/fixtures/https/snitest.org.cert"
      KeyFile = "integration/fixtures/https/snitest.org.key"
graceTimeOut = 10
logLevel = "DEBUG"

[file]

# rules
[backends]
  [backends.backend1]
    [backends.backend1.circuitbreaker]
      expression = "NetworkErrorRatio() > 0.5"
    [backends.backend1.servers.server1]
    url = "http://172.17.0.2:80"
    weight = 10
    [backends.backend1.servers.server2]
    url = "http://172.17.0.3:80"
    weight = 1
  [backends.backend2]
    [backends.backend2.LoadBalancer]
      method = "drr"
    [backends.backend2.servers.server1]
    url = "http://172.17.0.4:80"
    weight = 1
    [backends.backend2.servers.server2]
    url = "http://172.17.0.5:80"
    weight = 2

[frontends]
  [frontends.frontend1]
  backend = "backend2"
    [frontends.frontend1.routes.test_1]
    rule = "Host"
    value = "test.localhost"
  [frontends.frontend2]
  backend = "backend1"
  passHostHeader = true
  entrypoints = ["https"] # overrides defaultEntryPoints
    [frontends.frontend2.routes.test_1]
    rule = "Host"
    value = "{subdomain:[a-z]+}.localhost"
  [frontends.frontend3]
  entrypoints = ["http", "https"] # overrides defaultEntryPoints
  backend = "backend2"
    rule = "Path"
    value = "/test"
  • or put your rules in a separate file, for example rules.tml:
# traefik.toml
[entryPoints]
  [entryPoints.http]
  address = ":80"
    [entryPoints.http.redirect]
      entryPoint = "https"
  [entryPoints.https]
  address = ":443"
    [entryPoints.https.tls]
      [[entryPoints.https.tls.certificates]]
      CertFile = "integration/fixtures/https/snitest.com.cert"
      KeyFile = "integration/fixtures/https/snitest.com.key"
      [[entryPoints.https.tls.certificates]]
      CertFile = "integration/fixtures/https/snitest.org.cert"
      KeyFile = "integration/fixtures/https/snitest.org.key"
graceTimeOut = 10
logLevel = "DEBUG"

[file]
filename = "rules.toml"

# rules.toml
[backends]
  [backends.backend1]
    [backends.backend1.circuitbreaker]
      expression = "NetworkErrorRatio() > 0.5"
    [backends.backend1.servers.server1]
    url = "http://172.17.0.2:80"
    weight = 10
    [backends.backend1.servers.server2]
    url = "http://172.17.0.3:80"
    weight = 1
  [backends.backend2]
    [backends.backend2.LoadBalancer]
      method = "drr"
    [backends.backend2.servers.server1]
    url = "http://172.17.0.4:80"
    weight = 1
    [backends.backend2.servers.server2]
    url = "http://172.17.0.5:80"
    weight = 2

[frontends]
  [frontends.frontend1]
  backend = "backend2"
    [frontends.frontend1.routes.test_1]
    rule = "Host"
    value = "test.localhost"
  [frontends.frontend2]
  backend = "backend1"
  passHostHeader = true
  entrypoints = ["https"] # overrides defaultEntryPoints
    [frontends.frontend2.routes.test_1]
    rule = "Host"
    value = "{subdomain:[a-z]+}.localhost"
  [frontends.frontend3]
  entrypoints = ["http", "https"] # overrides defaultEntryPoints
  backend = "backend2"
    rule = "Path"
    value = "/test"

If you want Træfɪk to watch file changes automatically, just add:

[file]
watch = true

API backend

Træfik can be configured using a restful api. To enable it:

[web]
address = ":8080"

# SSL certificate and key used
#
# Optional
#
# CertFile = "traefik.crt"
# KeyFile = "traefik.key"
#
# Set REST API to read-only mode
#
# Optional
# ReadOnly = false
  • /: provides a simple HTML frontend of Træfik

Web UI Providers Web UI Health

  • /health: GET json metrics
$ curl -s "http://localhost:8080/health" | jq .
{
  // Træfɪk PID
  "pid": 2458,
  // Træfɪk server uptime (formated time)
  "uptime": "39m6.885931127s",
  //  Træfɪk server uptime in seconds
  "uptime_sec": 2346.885931127,
  // current server date
  "time": "2015-10-07 18:32:24.362238909 +0200 CEST",
  // current server date in seconds
  "unixtime": 1444235544,
  // count HTTP response status code in realtime
  "status_code_count": {
    "502": 1
  },
  // count HTTP response status code since Træfɪk started
  "total_status_code_count": {
    "200": 7,
    "404": 21,
    "502": 13
  },
  // count HTTP response
  "count": 1,
  // count HTTP response
  "total_count": 41,
  // sum of all response time (formated time)
  "total_response_time": "35.456865605s",
  // sum of all response time in seconds
  "total_response_time_sec": 35.456865605,
  // average response time (formated time)
  "average_response_time": "864.8016ms",
  // average response time in seconds
  "average_response_time_sec": 0.8648016000000001
}
  • /api: GET configuration for all providers
$ curl -s "http://localhost:8080/api" | jq .
{
  "file": {
    "frontends": {
      "frontend2": {
        "routes": {
          "test_2": {
            "value": "/test",
            "rule": "Path"
          }
        },
        "backend": "backend1"
      },
      "frontend1": {
        "routes": {
          "test_1": {
            "value": "test.localhost",
            "rule": "Host"
          }
        },
        "backend": "backend2"
      }
    },
    "backends": {
      "backend2": {
        "loadBalancer": {
          "method": "drr"
        },
        "servers": {
          "server2": {
            "weight": 2,
            "URL": "http://172.17.0.5:80"
          },
          "server1": {
            "weight": 1,
            "url": "http://172.17.0.4:80"
          }
        }
      },
      "backend1": {
        "loadBalancer": {
          "method": "wrr"
        },
        "circuitBreaker": {
          "expression": "NetworkErrorRatio() > 0.5"
        },
        "servers": {
          "server2": {
            "weight": 1,
            "url": "http://172.17.0.3:80"
          },
          "server1": {
            "weight": 10,
            "url": "http://172.17.0.2:80"
          }
        }
      }
    }
  }
}
  • /api/providers: GET providers
  • /api/providers/{provider}: GET or PUT provider
  • /api/providers/{provider}/backends: GET backends
  • /api/providers/{provider}/backends/{backend}: GET a backend
  • /api/providers/{provider}/backends/{backend}/servers: GET servers in a backend
  • /api/providers/{provider}/backends/{backend}/servers/{server}: GET a server in a backend
  • /api/providers/{provider}/frontends: GET frontends
  • /api/providers/{provider}/frontends/{frontend}: GET a frontend
  • /api/providers/{provider}/frontends/{frontend}/routes: GET routes in a frontend
  • /api/providers/{provider}/frontends/{frontend}/routes/{route}: GET a route in a frontend

Docker backend

Træfɪk can be configured to use Docker as a backend configuration:

################################################################
# Docker configuration backend
################################################################

# Enable Docker configuration backend
#
# Optional
#
[docker]

# Docker server endpoint. Can be a tcp or a unix socket endpoint.
#
# Required
#
endpoint = "unix:///var/run/docker.sock"

# Default domain used.
# Can be overridden by setting the "traefik.domain" label on a container.
#
# Required
#
domain = "docker.localhost"

# Enable watch docker changes
#
# Optional
#
watch = true

# Override default configuration template. For advanced users :)
#
# Optional
#
# filename = "docker.tmpl"

# Enable docker TLS connection
#
#  [docker.tls]
#  ca = "/etc/ssl/ca.crt"
#  cert = "/etc/ssl/docker.crt"
#  key = "/etc/ssl/docker.key"
#  insecureskipverify = true

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.protocol=https: override the default http protocol
  • traefik.weight=10: assign this weight to the container
  • traefik.enable=false: disable this container in Træfɪk
  • traefik.frontend.rule=Host: override the default frontend rule (Default: Host). See frontends.
  • traefik.frontend.value=test.example.com: override the default frontend value (Default: {containerName}.{domain}) See frontends. Must be associated with label traefik.frontend.rule.
  • traefik.frontend.passHostHeader=true: forward client Host header to the backend.
  • traefik.frontend.entryPoints=http,https: assign this frontend to entry points http and https. Overrides defaultEntryPoints.
  • traefik.domain=traefik.localhost: override the default domain

Marathon backend

Træfɪk can be configured to use Marathon as a backend configuration:

################################################################
# Mesos/Marathon configuration backend
################################################################

# Enable Marathon configuration backend
#
# Optional
#
[marathon]

# Marathon server endpoint.
# You can also specify multiple endpoint for Marathon:
# endpoint := "http://10.241.1.71:8080,10.241.1.72:8080,10.241.1.73:8080"
#
# Required
#
endpoint = "http://127.0.0.1:8080"

# Enable watch Marathon changes
#
# Optional
#
watch = true

# Default domain used.
# Can be overridden by setting the "traefik.domain" label on an application.
#
# Required
#
domain = "marathon.localhost"

# Override default configuration template. For advanced users :)
#
# Optional
#
# filename = "marathon.tmpl"

# Enable Marathon basic authentication
#
# Optional
#
#  [marathon.basic]
#  httpBasicAuthUser = "foo"
#  httpBasicPassword = "bar"

# TLS client configuration. https://golang.org/pkg/crypto/tls/#Config
#
# Optional
#
# [marathon.TLS]
# InsecureSkipVerify = true

Labels can be used on containers to override default behaviour:

  • traefik.backend=foo: assign the application to foo backend
  • traefik.portIndex=1: register port by index in the application's ports array. Useful when the application exposes multiple ports.
  • traefik.port=80: register the explicit application port value. Cannot be used alongside traefik.portIndex.
  • traefik.protocol=https: override the default http protocol
  • traefik.weight=10: assign this weight to the application
  • traefik.enable=false: disable this application in Træfɪk
  • traefik.frontend.rule=Host: override the default frontend rule (Default: Host). See frontends.
  • traefik.frontend.value=test.example.com: override the default frontend value (Default: {appName}.{domain}) See frontends. Must be associated with label traefik.frontend.rule.
  • traefik.frontend.passHostHeader=true: forward client Host header to the backend.
  • traefik.frontend.entryPoints=http,https: assign this frontend to entry points http and https. Overrides defaultEntryPoints.
  • traefik.domain=traefik.localhost: override the default domain

Consul backend

Træfɪk can be configured to use Consul as a backend configuration:

################################################################
# Consul KV configuration backend
################################################################

# Enable Consul KV configuration backend
#
# Optional
#
[consul]

# Consul server endpoint
#
# Required
#
endpoint = "127.0.0.1:8500"

# Enable watch Consul changes
#
# Optional
#
watch = true

# Prefix used for KV store.
#
# Optional
#
prefix = "traefik"

# Override default configuration template. For advanced users :)
#
# Optional
#
# filename = "consul.tmpl"

# Enable consul TLS connection
#
# Optional
#
# [consul.tls]
# ca = "/etc/ssl/ca.crt"
# cert = "/etc/ssl/consul.crt"
# key = "/etc/ssl/consul.key"
# insecureskipverify = true

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
  • 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
  • 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
  • frontend 2
Key Value
/traefik/frontends/frontend2/backend backend1
/traefik/frontends/frontend2/passHostHeader true
/traefik/frontends/frontend2/entrypoints http,https
/traefik/frontends/frontend2/routes/test_2/rule Path
/traefik/frontends/frontend2/routes/test_2/value /test

Etcd backend

Træfɪk can be configured to use Etcd as a backend configuration:

################################################################
# Etcd configuration backend
################################################################

# Enable Etcd configuration backend
#
# Optional
#
# [etcd]

# Etcd server endpoint
#
# Required
#
# endpoint = "127.0.0.1:4001"

# Enable watch Etcd changes
#
# Optional
#
# watch = true

# Prefix used for KV store.
#
# Optional
#
# prefix = "/traefik"

# Override default configuration template. For advanced users :)
#
# Optional
#
# filename = "etcd.tmpl"

# Enable etcd TLS connection
#
# Optional
#
# [etcd.tls]
# ca = "/etc/ssl/ca.crt"
# cert = "/etc/ssl/etcd.crt"
# key = "/etc/ssl/etcd.key"
# insecureskipverify = true

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
  • 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
  • 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
  • frontend 2
Key Value
/traefik/frontends/frontend2/backend backend1
/traefik/frontends/frontend2/passHostHeader true
/traefik/frontends/frontend2/entrypoints http,https
/traefik/frontends/frontend2/routes/test_2/rule Path
/traefik/frontends/frontend2/routes/test_2/value /test

Consul catalog backend

Træfɪk can be configured to use service discovery catalog of Consul as a backend configuration:

################################################################
# Consul Catalog configuration backend
################################################################

# Enable Consul Catalog configuration backend
#
# Optional
#
[consulCatalog]

# Consul server endpoint
#
# Required
#
endpoint = "127.0.0.1:8500"

# Default domain used.
#
# Optional
#
domain = "consul.localhost"

This backend will create routes matching on hostname based on the service name used in consul.

Zookeeper backend

Træfɪk can be configured to use Zookeeper as a backend configuration:

################################################################
# Zookeeper configuration backend
################################################################

# Enable Zookeeperconfiguration backend
#
# Optional
#
# [zookeeper]

# Zookeeper server endpoint
#
# Required
#
# endpoint = "127.0.0.1:2181"

# Enable watch Zookeeper changes
#
# Optional
#
# watch = true

# Prefix used for KV store.
#
# Optional
#
# prefix = "/traefik"

# Override default configuration template. For advanced users :)
#
# Optional
#
# filename = "zookeeper.tmpl"

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
  • 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
  • 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
  • frontend 2
Key Value
/traefik/frontends/frontend2/backend backend1
/traefik/frontends/frontend2/passHostHeader true
/traefik/frontends/frontend2/entrypoints http,https
/traefik/frontends/frontend2/routes/test_2/rule Path
/traefik/frontends/frontend2/routes/test_2/value /test

BoltDB backend

Træfɪk can be configured to use BoltDB as a backend configuration:

################################################################
# BoltDB configuration backend
################################################################

# Enable BoltDB configuration backend
#
# Optional
#
# [boltdb]

# BoltDB file
#
# Required
#
# endpoint = "/my.db"

# Enable watch BoltDB changes
#
# Optional
#
# watch = true

# Prefix used for KV store.
#
# Optional
#
# prefix = "/traefik"

# Override default configuration template. For advanced users :)
#
# Optional
#
# filename = "boltdb.tmpl"

Atomic configuration changes

The Etcd and Consul backends do not support updating multiple keys atomically. As a result, it may be possible for Træfɪk to read an intermediate configuration state despite judicious use of the --providersThrottleDuration flag. To solve this problem, Træfɪk supports a special key called /traefik/alias. If set, Træfɪk use the value as an alternative key prefix.

Given the key structure below, Træfɪk will use the http://172.17.0.2:80 as its only backend (frontend keys have been omitted for brevity).

Key Value
/traefik/alias /traefik_configurations/1
/traefik_configurations/1/backends/backend1/servers/server1/url http://172.17.0.2:80
/traefik_configurations/1/backends/backend1/servers/server1/weight 10

When an atomic configuration change is required, you may write a new configuration at an alternative prefix. Here, although the /traefik_configurations/2/... keys have been set, the old configuration is still active because the /traefik/alias key still points to /traefik_configurations/1:

Key Value
/traefik/alias /traefik_configurations/1
/traefik_configurations/1/backends/backend1/servers/server1/url http://172.17.0.2:80
/traefik_configurations/1/backends/backend1/servers/server1/weight 10
/traefik_configurations/2/backends/backend1/servers/server1/url http://172.17.0.2:80
/traefik_configurations/2/backends/backend1/servers/server1/weight 5
/traefik_configurations/2/backends/backend1/servers/server2/url http://172.17.0.3:80
/traefik_configurations/2/backends/backend1/servers/server2/weight 5

Once the /traefik/alias key is updated, the new /traefik_configurations/2 configuration becomes active atomically. Here, we have a 50% balance between the http://172.17.0.3:80 and the http://172.17.0.4:80 hosts while no traffic is sent to the 172.17.0.2:80 host:

Key Value
/traefik/alias /traefik_configurations/2
/traefik_configurations/1/backends/backend1/servers/server1/url http://172.17.0.2:80
/traefik_configurations/1/backends/backend1/servers/server1/weight 10
/traefik_configurations/2/backends/backend1/servers/server1/url http://172.17.0.3:80
/traefik_configurations/2/backends/backend1/servers/server1/weight 5
/traefik_configurations/2/backends/backend1/servers/server2/url http://172.17.0.4:80
/traefik_configurations/2/backends/backend1/servers/server2/weight 5

Note that Træfɪk will not watch for key changes in the /traefik_configurations prefix. It will only watch for changes in the /traefik prefix. Further, if the /traefik/alias key is set, all other sibling keys with the /traefik prefix are ignored.

Benchmarks

Here are some early Benchmarks between Nginx, HA-Proxy and Træfɪk acting as simple load balancers between two servers.

  • Nginx:
$ docker run -d -e VIRTUAL_HOST=test.nginx.localhost emilevauge/whoami
$ docker run -d -e VIRTUAL_HOST=test.nginx.localhost emilevauge/whoami
$ docker run --log-driver=none -d -p 80:80 -v /var/run/docker.sock:/tmp/docker.sock:ro jwilder/nginx-proxy
$ wrk -t12 -c400 -d60s -H "Host: test.nginx.localhost" --latency http://127.0.0.1:80
Running 1m test @ http://127.0.0.1:80
  12 threads and 400 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency   162.61ms  203.34ms   1.72s    91.07%
    Req/Sec   277.57    107.67   790.00     67.53%
  Latency Distribution
     50%  128.19ms
     75%  218.22ms
     90%  342.12ms
     99%    1.08s 
  197991 requests in 1.00m, 82.32MB read
  Socket errors: connect 0, read 0, write 0, timeout 18
Requests/sec:   3296.04
Transfer/sec:      1.37MB
  • HA-Proxy:
$ docker run -d --name web1 -e VIRTUAL_HOST=test.haproxy.localhost emilevauge/whoami
$ docker run -d --name web2 -e VIRTUAL_HOST=test.haproxy.localhost emilevauge/whoami
$ docker run -d -p 80:80 --link web1:web1 --link web2:web2 dockercloud/haproxy
$ wrk -t12 -c400 -d60s -H "Host: test.haproxy.localhost" --latency http://127.0.0.1:80
Running 1m test @ http://127.0.0.1:80
  12 threads and 400 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency   158.08ms  187.88ms   1.75s    89.61%
    Req/Sec   281.33    120.47     0.98k    65.88%
  Latency Distribution
     50%  121.77ms
     75%  227.10ms
     90%  351.98ms
     99%    1.01s 
  200462 requests in 1.00m, 59.65MB read
Requests/sec:   3337.66
Transfer/sec:      0.99MB
  • Træfɪk:
$ docker run -d -l traefik.backend=test1 -l traefik.frontend.rule=Host -l traefik.frontend.value=test.traefik.localhost emilevauge/whoami
$ docker run -d -l traefik.backend=test1 -l traefik.frontend.rule=Host -l traefik.frontend.value=test.traefik.localhost emilevauge/whoami
$ docker run -d -p 8080:8080 -p 80:80 -v $PWD/traefik.toml:/traefik.toml -v /var/run/docker.sock:/var/run/docker.sock containous/traefik
$ wrk -t12 -c400 -d60s -H "Host: test.traefik.localhost" --latency http://127.0.0.1:80
Running 1m test @ http://127.0.0.1:80
  12 threads and 400 connections
  Thread Stats   Avg      Stdev     Max   +/- Stdev
    Latency   132.93ms  121.89ms   1.20s    66.62%
    Req/Sec   280.95    104.88   740.00     68.26%
  Latency Distribution
     50%  128.71ms
     75%  214.15ms
     90%  281.45ms
     99%  498.44ms
  200734 requests in 1.00m, 80.02MB read
Requests/sec:   3340.13
Transfer/sec:      1.33MB