emile f37349fff7 Documentation corrections

2015-09-24 10:01:57 +02:00

11 KiB

Raw Blame History

Documentation

Basics
Global configuration
File backend
API backend
Docker backend
Mesos/Marathon backend
Consul backend

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]+}
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.

HTTP Backends

A backend is responsible to load-balance the traffic coming from one or more frontends to a set of http servers. Various types of load-balancing is supported:

Weighted round robin
Rebalancer: 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.

Global configuration

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

# Reverse proxy port
#
# Optional
# Default: ":80"
#
# port = ":80"

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

# Traefik logs file
#
# Optional
#
# traefikLogsFile = "log/traefik.log"

# Traefik log to standard output
#
# Optional
# Default: true
#
# traefikLogsStdout = true

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

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

# SSL certificate and key used
#
# Optional
#
# CertFile = "traefik.crt"
# KeyFile = "traefik.key"

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
port = ":80"
graceTimeOut = 10
logLevel = "DEBUG"
traefikLogsStdout = true

[file]

# rules
[backends]
  [backends.backend1]
    [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.servers.server1]
    url = "http://172.17.0.4:80"
    weight = 1

 [frontends]
   [frontends.frontend1]
   backend = "backend2"
     [frontends.frontend1.routes.test_1]
     rule = "Host"
     value = "test.localhost"
   [frontends.frontend2]
   backend = "backend1"
     [frontends.frontend2.routes.test_2]
     rule = "Path"
     value = "/test"

or put your rules in a separate file, for example rules.tml:

# traefik.toml
port = ":80"
graceTimeOut = 10
logLevel = "DEBUG"
traefikLogsStdout = true

[file]
filename = "rules.toml"

# rules.toml
[backends]
  [backends.backend1]
    [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.servers.server1]
    url = "http://172.17.0.4:80"
    weight = 1

[frontends]
  [frontends.frontend1]
  backend = "backend2"
    [frontends.frontend1.routes.test_1]
    rule = "Host"
    value = "test.localhost"
  [frontends.frontend2]
  backend = "backend1"
    [frontends.frontend2.routes.test_2]
    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"

/: provides a simple HTML frontend of Træfik

/health: GET json metrics

$ curl -s "http://localhost:8080/health" | jq .
{
  "average_response_time_sec": 0,
  "average_response_time": "0",
  "total_response_time_sec": 0,
  "total_response_time": "0",
  "total_count": 0,
  "pid": 12861,
  "uptime": "7m12.80607635s",
  "uptime_sec": 432.80607635,
  "time": "2015-09-22 10:25:16.448023473 +0200 CEST",
  "unixtime": 1442910316,
  "status_code_count": {},
  "total_status_code_count": {},
  "count": 0
}

/api: GET or PUT a configuration

$ curl -s "http://localhost:8082/api" | jq .
{
  "Frontends": {
    "frontend-traefik": {
      "Routes": {
        "route-host-traefik": {
          "Value": "traefik.docker.localhost",
          "Rule": "Host"
        }
      },
      "Backend": "backend-test2"
    },
    "frontend-test": {
      "Routes": {
        "route-host-test": {
          "Value": "test.docker.localhost",
          "Rule": "Host"
        }
      },
      "Backend": "backend-test1"
    }
  },
  "Backends": {
    "backend-test2": {
      "Servers": {
        "server-stoic_brattain": {
          "Weight": 0,
          "Url": "http://172.17.0.8:80"
        },
        "server-jovial_khorana": {
          "Weight": 0,
          "Url": "http://172.17.0.12:80"
        },
        "server-jovial_franklin": {
          "Weight": 0,
          "Url": "http://172.17.0.11:80"
        },
        "server-elegant_panini": {
          "Weight": 0,
          "Url": "http://172.17.0.9:80"
        },
        "server-adoring_elion": {
          "Weight": 0,
          "Url": "http://172.17.0.10:80"
        }
      }
    },
    "backend-test1": {
      "Servers": {
        "server-trusting_wozniak": {
          "Weight": 0,
          "Url": "http://172.17.0.5:80"
        },
        "server-sharp_jang": {
          "Weight": 0,
          "Url": "http://172.17.0.7:80"
        },
        "server-dreamy_feynman": {
          "Weight": 0,
          "Url": "http://172.17.0.6:80"
        }
      }
    }
  }
}

/api/backends: GET backends
/api/backends/{backend}: GET a backend
/api/backends/{backend}/servers: GET servers in a backend
/api/backends/{backend}/servers/{server}: GET a server in a backend
/api/frontends: GET frontends
/api/frontends/{frontend}: GET 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"

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}

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"

# Network interface used to call Marathon web services
# Optional
# Default: "eth0"
#
# networkInterface = "eth0"

# 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"