From 38cc36980f25582cf4b64aca1453de34ca9fcb4a Mon Sep 17 00:00:00 2001 From: Martin Date: Mon, 11 Jul 2016 17:32:28 +0200 Subject: [PATCH] update doc --- docs/basics.md | 55 ++++++- docs/toml.md | 89 +---------- docs/user-guide/examples.md | 1 + docs/user-guide/kv-config.md | 298 +++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 +- 5 files changed, 352 insertions(+), 93 deletions(-) create mode 100644 docs/user-guide/kv-config.md diff --git a/docs/basics.md b/docs/basics.md index c6a4145ee..41966e3b3 100644 --- a/docs/basics.md +++ b/docs/basics.md @@ -253,9 +253,30 @@ Here is an example of backends and servers definition: - `backend2` will forward the traffic to two servers: `http://172.17.0.4:80"` with weight `1` and `http://172.17.0.5:80` with weight `2` using `drr` load-balancing strategy. - a circuit breaker is added on `backend1` using the expression `NetworkErrorRatio() > 0.5`: watch error ratio over 10 second sliding window -# Launch +# Configuration + +Træfɪk's configuration has two parts: + +- The [static Træfɪk configuration](/basics#static-trfk-configuration) which is loaded only at the begining. +- The [dynamic Træfɪk configuration](/basics#dynamic-trfk-configuration) which can be hot-reloaded (no need to restart the process). + + +## Static Træfɪk configuration + +The static configuration is the global configuration which setting up connections to configuration backends and entrypoints. + +Træfɪk can be configured using many configuration sources with the following precedence order. +Each item takes precedence over the item below it: + +- [Key-value Store](/basics/#key-value-stores) +- [Arguments](/basics/#arguments) +- [Configuration file](/basics/#configuration-file) +- Default + +It means that arguments overrides configuration file, and Key-value Store overrides arguments. + +### Configuration file -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/` @@ -268,15 +289,35 @@ 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: +Please refer to the [global configuration](/toml/#global-configuration) section to get documentation on it. -- arguments -- configuration file -- default +### Arguments -It means that arguments overrides configuration file. Each argument is described in the help section: ```bash $ traefik --help ``` + +Note that all default values will be displayed as well. + +### Key-value stores + +Træfɪk supports several Key-value stores: + +- [Consul](https://consul.io) +- [etcd](https://coreos.com/etcd/) +- [ZooKeeper](https://zookeeper.apache.org/) +- [boltdb](https://github.com/boltdb/bolt) + +Please refer to the [User Guide Key-value store configuration](/user-guide/kv-config/) section to get documentation on it. + +## Dynamic Træfɪk configuration + +Træfɪk can hot-reload its configuration. + +The dynamic configuration concern route rules which could be provided by [multiple configuration backends](/toml/#configuration-backends). +We only need to enable `watch` option to make Træfɪk watch configuration backend changes and generate its configuration automatically. +Routes to services will be created and updated instantly at any changes. + +Please refer to the [configuration backends](/toml/#configuration-backends) section to get documentation on it. diff --git a/docs/toml.md b/docs/toml.md index 8028206ea..8cfded1ea 100644 --- a/docs/toml.md +++ b/docs/toml.md @@ -756,7 +756,7 @@ prefix = "traefik" # insecureskipverify = true ``` -Please refer to the [Key Value storage structure](#key-value-storage-structure) section to get documentation en traefik KV structure. +Please refer to the [Key Value storage structure](/user-guide/kv-config/#key-value-storage-structure) section to get documentation on traefik KV structure. ## Consul catalog backend @@ -857,7 +857,7 @@ prefix = "/traefik" # insecureskipverify = true ``` -Please refer to the [Key Value storage structure](#key-value-storage-structure) section to get documentation en traefik KV structure. +Please refer to the [Key Value storage structure](/user-guide/kv-config/#key-value-storage-structure) section to get documentation on traefik KV structure. ## Zookeeper backend @@ -900,7 +900,7 @@ prefix = "/traefik" # filename = "zookeeper.tmpl" ``` -Please refer to the [Key Value storage structure](#key-value-storage-structure) section to get documentation en traefik KV structure. +Please refer to the [Key Value storage structure](/user-guide/kv-config/#key-value-storage-structure) section to get documentation on traefik KV structure. ## BoltDB backend @@ -942,85 +942,4 @@ prefix = "/traefik" # filename = "boltdb.tmpl" ``` -Please refer to the [Key Value storage structure](#key-value-storage-structure) section to get documentation en traefik KV structure. - -## Key-value storage structure - -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/maxconn/amount` | `10` | -| `/traefik/backends/backend2/maxconn/extractorfunc` | `request.host` | -| `/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:test.localhost` | - -- frontend 2 - -| Key | Value | -|----------------------------------------------------|--------------------| -| `/traefik/frontends/frontend2/backend` | `backend1` | -| `/traefik/frontends/frontend2/passHostHeader` | `true` | -| `/traefik/frontends/frontend2/priority` | `10` | -| `/traefik/frontends/frontend2/entrypoints` | `http,https` | -| `/traefik/frontends/frontend2/routes/test_2/rule` | `PathPrefix:/test` | - -## Atomic configuration changes - -The [Etcd](https://github.com/coreos/etcd/issues/860) and [Consul](https://github.com/hashicorp/consul/issues/886) 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. +Please refer to the [Key Value storage structure](/user-guide/kv-config/#key-value-storage-structure) section to get documentation on traefik KV structure. diff --git a/docs/user-guide/examples.md b/docs/user-guide/examples.md index cf164755c..ad4d9fa52 100644 --- a/docs/user-guide/examples.md +++ b/docs/user-guide/examples.md @@ -29,6 +29,7 @@ defaultEntryPoints = ["http", "https"] CertFile = "integration/fixtures/https/snitest.org.cert" KeyFile = "integration/fixtures/https/snitest.org.key" ``` +Note that we can either give path to certificate file or directly the file content itself ([like in this TOML example](/user-guide/kv-config/#upload-the-configuration-in-the-key-value-store)). ## HTTP redirect on HTTPS diff --git a/docs/user-guide/kv-config.md b/docs/user-guide/kv-config.md new file mode 100644 index 000000000..264722e1d --- /dev/null +++ b/docs/user-guide/kv-config.md @@ -0,0 +1,298 @@ + +# Key-value store configuration + +Both [static global configuration](/user-guide/kv-config/#static-configuration-in-key-value-store) and [dynamic](/user-guide/kv-config/#dynamic-configuration-in-key-value-store) configuration can be sorted in a Key-value store. + +This section explains how to launch Træfɪk using a configuration loaded from a Key-value store. + +Træfɪk supports several Key-value stores: + +- [Consul](https://consul.io) +- [etcd](https://coreos.com/etcd/) +- [ZooKeeper](https://zookeeper.apache.org/) +- [boltdb](https://github.com/boltdb/bolt) + +# Static configuration in Key-value store + +We will see the steps to set it up with an easy example. +Note that we could do the same with any other Key-value Store. + +## docker-compose file for Consul + +The Træfɪk global configuration will be getted from a [Consul](https://consul.io) store. + +First we have to launch Consul in a container. +The [docker-compose file](https://docs.docker.com/compose/compose-file/) allows us to launch Consul and four instances of the trivial app [emilevauge/whoamI](https://github.com/emilevauge/whoamI) : + +```yml +consul: + image: progrium/consul + command: -server -bootstrap -log-level debug -ui-dir /ui + ports: + - "8400:8400" + - "8500:8500" + - "8600:53/udp" + expose: + - "8300" + - "8301" + - "8301/udp" + - "8302" + - "8302/udp" + +whoami1: + image: emilevauge/whoami + +whoami2: + image: emilevauge/whoami + +whoami3: + image: emilevauge/whoami + +whoami4: + image: emilevauge/whoami +``` + +## Upload the configuration in the Key-value store + +We should now fill the store with the Træfɪk global configuration, as we do with a [TOML file configuration](/toml). +To do that, we can send the Key-value pairs via [curl commands](https://www.consul.io/intro/getting-started/kv.html) or via the [Web UI](https://www.consul.io/intro/getting-started/ui.html) + +Here the toml configuration we would like to store in the Key-value Store : + +```toml +logLevel = "DEBUG" + +defaultEntryPoints = ["http", "https"] + +[entryPoints] + [entryPoints.http] + address = ":80" + [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 = """-----BEGIN CERTIFICATE----- + + -----END CERTIFICATE-----""" + KeyFile = """-----BEGIN CERTIFICATE----- + + -----END CERTIFICATE-----""" + + +[consul] + endpoint = "127.0.0.1:8500" + watch = true + prefix = "traefik" + +[web] + address = ":8081" +``` + +And there, the same global configuration in the Key-value Store (using `prefix = "traefik"`): + +| Key | Value | +|-----------------------------------------------------------|---------------------------------------------------------------| +| `/traefik/loglevel` | `DEBUG` | +| `/traefik/defaultentrypoints/0` | `http` | +| `/traefik/defaultentrypoints/1` | `https` | +| `/traefik/entrypoints/http/address` | `:80` | +| `/traefik/entrypoints/https/address` | `:443` | +| `/traefik/entrypoints/https/tls/certificates/0/certfile` | `integration/fixtures/https/snitest.com.cert` | +| `/traefik/entrypoints/https/tls/certificates/0/keyfile` | `integration/fixtures/https/snitest.com.key` | +| `/traefik/entrypoints/https/tls/certificates/1/certfile` | `--BEGIN CERTIFICATE----END CERTIFICATE--` | +| `/traefik/entrypoints/https/tls/certificates/1/keyfile` | `--BEGIN CERTIFICATE----END CERTIFICATE--` | +| `/traefik/consul/endpoint` | `127.0.0.1:8500` | +| `/traefik/consul/watch` | `true` | +| `/traefik/consul/prefix` | `traefik` | +| `/traefik/web/address` | `:8081` | + +Remember to specify the indexes (`0`,`1`, `2`, ... ) under prefixes `/traefik/defaultentrypoints/` and `/traefik/entrypoints/https/tls/certificates/` in order to match the global configuration structure. + +Be careful to give the correct IP address and port on the key `/traefik/consul/endpoint`. + +Note that we can either give path to certificate file or directly the file content itself. + +## Launch Træfɪk + +We will now launch Træfɪk in a container. +We use CLI flags to setup the connection between Træfɪk and Consul. +All the rest of the global configuration is stored in Consul. + +Here the [docker-compose file](https://docs.docker.com/compose/compose-file/) : + +```yml +traefik: + image: traefik + command: --consul --consul.endpoint=127.0.0.1:8500 + ports: + - "80:80" + - "8080:8080" + volumes: + - /var/run/docker.sock:/var/run/docker.sock +``` + +NB : Be careful to give the correct IP address and port in the flag `--consul.endpoint`. + +## TLS support + +So far, only [Consul](https://consul.io) and [etcd](https://coreos.com/etcd/) support TLS connections. +To set it up, we should enable [consul security](https://www.consul.io/docs/internals/security.html) (or [etcd security](https://coreos.com/etcd/docs/latest/security.html)). + +Then, we have to provide CA, Cert and Key to Træfɪk using `consul` flags : + +- `--consul.tls` +- `--consul.tls.ca=path/to/the/file` +- `--consul.tls.cert=path/to/the/file` +- `--consul.tls.key=path/to/the/file` + +Or etcd flags : + +- `--etcd.tls` +- `--etcd.tls.ca=path/to/the/file` +- `--etcd.tls.cert=path/to/the/file` +- `--etcd.tls.key=path/to/the/file` + +Note that we can either give directly directly the file content itself (instead of the path to certificate) in a TOML file configuration. + +Remember the command `traefik --help` to display the updated list of flags. + +# Dynamic configuration in Key-value store +Following our example, we will provide backends/frontends rules to Træfɪk. + +Note that this section is independent of the way Træfɪk got its static configuration. +It means that the static configuration can either come from the same Key-value store or from any other sources. + +## Key-value storage structure +Here the toml configuration we would like to store in the store : + +```toml +[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.backend1.maxconn] + amount = 10 + extractorfunc = "request.host" + [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:test.localhost" + [frontends.frontend2] + backend = "backend1" + passHostHeader = true + priority = 10 + entrypoints = ["https"] # overrides defaultEntryPoints + [frontends.frontend2.routes.test_1] + rule = "Host:{subdomain:[a-z]+}.localhost" + [frontends.frontend3] + entrypoints = ["http", "https"] # overrides defaultEntryPoints + backend = "backend2" + rule = "Path:/test" +``` + +And there, the same dynamic configuration in a KV Store (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/maxconn/amount` | `10` | +| `/traefik/backends/backend2/maxconn/extractorfunc` | `request.host` | +| `/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:test.localhost` | + +- frontend 2 + +| Key | Value | +|----------------------------------------------------|--------------------| +| `/traefik/frontends/frontend2/backend` | `backend1` | +| `/traefik/frontends/frontend2/passHostHeader` | `true` | +| `/traefik/frontends/frontend2/priority` | `10` | +| `/traefik/frontends/frontend2/entrypoints` | `http,https` | +| `/traefik/frontends/frontend2/routes/test_2/rule` | `PathPrefix:/test` | + +## Atomic configuration changes + +Træfɪk can watch the backends/frontends configuration changes and generate its configuration automatically. + +Note that only backends/frontends rules are dynamic, the rest of the Træfɪk configuration stay static. + +The [Etcd](https://github.com/coreos/etcd/issues/860) and [Consul](https://github.com/hashicorp/consul/issues/886) 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/alias`. +Further, if the `/traefik/alias` key is set, all other configuration with `/traefik/backends` or `/traefik/frontends` prefix are ignored. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 08191d62b..be6298810 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,4 +50,4 @@ pages: - 'Configuration examples': 'user-guide/examples.md' - 'Swarm cluster': 'user-guide/swarm.md' - 'Kubernetes': 'user-guide/kubernetes.md' - - Benchmarks: benchmarks.md + - 'Key-value store configuration': 'user-guide/kv-config.md'