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

Merge pull request #1516 from ldez/refactor/documentation-review

Browse source 
doc: small documentation review
This commit is contained in:
Emile Vauge 2017-05-01 18:32:20 +02:00 committed by GitHub
commit bec45bc7d6
9 changed files with 100 additions and 98 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

64
docs/basics.md
View file

@ -161,34 +161,34 @@ As seen in the previous example, you can combine multiple rules.
In TOML file, you can use multiple routes:
```toml
[frontends.frontend3]
backend = "backend2"
[frontends.frontend3.routes.test_1]
rule = "Host:test3.localhost"
[frontends.frontend3.routes.test_2]
rule = "Path:/test"
[frontends.frontend3]
backend = "backend2"
[frontends.frontend3.routes.test_1]
rule = "Host:test3.localhost"
[frontends.frontend3.routes.test_2]
rule = "Path:/test"
```
Here `frontend3` will forward the traffic to the `backend2` if the rules `Host:test3.localhost` **AND** `Path:/test` are matched.
You can also use the notation using a `;` separator, same result:
```toml
[frontends.frontend3]
backend = "backend2"
[frontends.frontend3.routes.test_1]
rule = "Host:test3.localhost;Path:/test"
[frontends.frontend3]
backend = "backend2"
[frontends.frontend3.routes.test_1]
rule = "Host:test3.localhost;Path:/test"
```
Finally, you can create a rule to bind multiple domains or Path to a frontend, using the `,` separator:
```toml
[frontends.frontend2]
[frontends.frontend2.routes.test_1]
rule = "Host:test1.localhost,test2.localhost"
[frontends.frontend3]
backend = "backend2"
[frontends.frontend3.routes.test_1]
rule = "Path:/test1,/test2"
[frontends.frontend2]
[frontends.frontend2.routes.test_1]
rule = "Host:test1.localhost,test2.localhost"
[frontends.frontend3]
backend = "backend2"
[frontends.frontend3.routes.test_1]
rule = "Path:/test1,/test2"
```
### Priorities
@ -198,20 +198,20 @@ By default, routes will be sorted (in descending order) using rules length (to a
You can customize priority by frontend:
```
[frontends]
[frontends.frontend1]
backend = "backend1"
priority = 10
passHostHeader = true
[frontends.frontend1.routes.test_1]
rule = "PathPrefix:/to"
[frontends.frontend2]
priority = 5
backend = "backend2"
passHostHeader = true
[frontends.frontend2.routes.test_1]
rule = "PathPrefix:/toto"
```toml
[frontends]
[frontends.frontend1]
backend = "backend1"
priority = 10
passHostHeader = true
[frontends.frontend1.routes.test_1]
rule = "PathPrefix:/to"
[frontends.frontend2]
priority = 5
backend = "backend2"
passHostHeader = true
[frontends.frontend2.routes.test_1]
rule = "PathPrefix:/toto"
```
Here, `frontend1` will be matched before `frontend2` (`10 > 5`).
@ -412,7 +412,7 @@ Each command may have related flags.
All those related flags will be displayed with :
```bash
$ traefik [command] --help
$ traefik [command] --help
```
Note that each command is described at the beginning of the help section:

8
docs/benchmarks.md
View file

@ -117,7 +117,7 @@ server {
Here is the `traefik.toml` file used:
```
```toml
MaxIdleConnsPerHost = 100000
defaultEntryPoints = ["http"]
@ -145,7 +145,7 @@ defaultEntryPoints = ["http"]
## Results
### whoami:
```
```shell
wrk -t20 -c1000 -d60s -H "Host: test.traefik" --latency http://IP-whoami:80/bench
Running 1m test @ http://IP-whoami:80/bench
20 threads and 1000 connections
@ -164,7 +164,7 @@ Transfer/sec: 6.40MB
```
### nginx:
```
```shell
wrk -t20 -c1000 -d60s -H "Host: test.traefik" --latency http://IP-nginx:8001/bench
Running 1m test @ http://IP-nginx:8001/bench
20 threads and 1000 connections
@ -183,7 +183,7 @@ Transfer/sec: 4.97MB
```
### traefik:
```
```shell
wrk -t20 -c1000 -d60s -H "Host: test.traefik" --latency http://IP-traefik:8000/bench
Running 1m test @ http://IP-traefik:8000/bench
20 threads and 1000 connections

4
docs/index.md
View file

@ -121,14 +121,14 @@ networks:
Then, start and scale it in the `test` folder:
```
```shell
docker-compose up -d
docker-compose scale whoami=2
```
Finally, test load-balancing between the two services `test_whoami_1` and `test_whoami_2`:
```bash
```shell
$ curl -H Host:whoami.docker.localhost http://127.0.0.1
Hostname: ef194d07634a
IP: 127.0.0.1

20
docs/toml.md
View file

@ -120,9 +120,9 @@ Supported backends:
Supported filters:
- ```tag```
- `tag`
```
```toml
# Constraints definition
#
# Optional
@ -619,7 +619,7 @@ address = ":8080"
- `/ping`: `GET` simple endpoint to check for Træfik process liveness.
```sh
```shell
$ curl -sv "http://localhost:8080/ping"
* Trying ::1...
* Connected to localhost (::1) port 8080 (#0)
@ -639,7 +639,7 @@ OK
- `/health`: `GET` json metrics
```sh
```shell
$ curl -s "http://localhost:8080/health" | jq .
{
// Træfik PID
@ -698,7 +698,7 @@ $ curl -s "http://localhost:8080/health" | jq .
- `/api`: `GET` configuration for all providers
```sh
```shell
$ curl -s "http://localhost:8080/api" | jq .
{
"file": {
@ -1717,12 +1717,12 @@ RefreshSeconds = 15
```
Items in the dynamodb table must have three attributes:
Items in the `dynamodb` table must have three attributes:
- 'id' : string
- `id` : string
- The id is the primary key.
- 'name' : string
- `name` : string
- The name is used as the name of the frontend or backend.
- 'frontend' or 'backend' : map
- This attribute's structure matches exactly the structure of a Frontend or Backend type in traefik. See types/types.go for details. The presence or absence of this attribute determines its type. So an item should never have both a 'frontend' and a 'backend' attribute.
- `frontend` or `backend` : map
- This attribute's structure matches exactly the structure of a Frontend or Backend type in traefik. See `types/types.go` for details. The presence or absence of this attribute determines its type. So an item should never have both a `frontend` and a `backend` attribute.

16
docs/user-guide/examples.md
View file

@ -5,7 +5,7 @@ You will find here some configuration examples of Træfik.
## HTTP only
```
```toml
defaultEntryPoints = ["http"]
[entryPoints]
[entryPoints.http]
@ -14,7 +14,7 @@ defaultEntryPoints = ["http"]
## HTTP + HTTPS (with SNI)
```
```toml
defaultEntryPoints = ["http", "https"]
[entryPoints]
[entryPoints.http]
@ -33,7 +33,7 @@ Note that we can either give path to certificate file or directly the file conte
## HTTP redirect on HTTPS
```
```toml
defaultEntryPoints = ["http", "https"]
[entryPoints]
[entryPoints.http]
@ -50,7 +50,7 @@ defaultEntryPoints = ["http", "https"]
## Let's Encrypt support
```
```toml
[entryPoints]
[entryPoints.https]
address = ":443"
@ -80,7 +80,7 @@ entryPoint = "https"
## Override entrypoints in frontends
```
```toml
[frontends]
[frontends.frontend1]
backend = "backend2"
@ -107,7 +107,7 @@ With two user/pass:
Passwords are encoded in MD5: you can use htpasswd to generate those ones.
```
```toml
defaultEntryPoints = ["http"]
[entryPoints]
[entryPoints.http]
@ -121,7 +121,7 @@ defaultEntryPoints = ["http"]
Providing an authentication method as described above, it is possible to pass the user to the application
via a configurable header value
```
```toml
defaultEntryPoints = ["http"]
[entryPoints]
[entryPoints.http]
@ -134,7 +134,7 @@ defaultEntryPoints = ["http"]
## Override the Traefik HTTP server IdleTimeout and/or throttle configurations from re-loading too quickly
```
```toml
IdleTimeout = "360s"
ProvidersThrottleDuration = "5s"
```

22
docs/user-guide/kubernetes.md
View file

@ -206,7 +206,7 @@ spec:
```
[examples/k8s/ui.yaml](https://github.com/containous/traefik/tree/master/examples/k8s/ui.yaml)
```sh
```shell
kubectl apply -f examples/k8s/ui.yaml
```
@ -217,7 +217,7 @@ to our cluster.
> You can get the ip address of your minikube instance by running `minikube ip`
```
```shell
echo "$(minikube ip) traefik-ui.local" | sudo tee -a /etc/hosts
```
@ -333,7 +333,7 @@ spec:
```
[examples/k8s/cheese-deployments.yaml](https://github.com/containous/traefik/tree/master/examples/k8s/cheese-deployments.yaml)
```sh
```shell
kubectl apply -f examples/k8s/cheese-deployments.yaml
```
@ -389,7 +389,7 @@ spec:
[examples/k8s/cheese-services.yaml](https://github.com/containous/traefik/tree/master/examples/k8s/cheese-services.yaml)
```sh
```shell
kubectl apply -f examples/k8s/cheese-services.yaml
```
@ -430,7 +430,7 @@ spec:
> Notice that we list each hostname, and add a backend service.
```sh
```shell
kubectl apply -f examples/k8s/cheese-ingress.yaml
```
@ -441,7 +441,7 @@ with a Server set up for each pod.
If you edit your `/etc/hosts` again you should be able to access the cheese
websites in your browser.
```sh
```shell
echo "$(minikube ip) stilton.local cheddar.local wensleydale.local" | sudo tee -a /etc/hosts
```
@ -490,11 +490,11 @@ spec:
> with the `traefik.frontend.rule.type` annotation so that we can use
> the containers from the previous example without modification.
```sh
```shell
kubectl apply -f examples/k8s/cheeses-ingress.yaml
```
```sh
```shell
echo "$(minikube ip) cheeses.local" | sudo tee -a /etc/hosts
```
@ -562,7 +562,11 @@ could set `disablePassHostHeaders` to true in your toml file and then enable pas
the host header per ingress if you wanted.
## Excluding an ingress from Træfik
You can control which ingress Træfik cares about by using the "kubernetes.io/ingress.class"
You can control which ingress Træfik cares about by using the `kubernetes.io/ingress.class`
annotation. By default if the annotation is not set at all Træfik will include the
ingress. If the annotation is set to anything other than traefik or a blank string
Træfik will ignore it.
![](http://i.giphy.com/ujUdrdpX7Ok5W.gif)

17
docs/user-guide/kv-config.md
View file

@ -24,7 +24,7 @@ The Træfik global configuration will be getted from a [Consul](https://consul.i
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
```yaml
consul:
image: progrium/consul
command: -server -bootstrap -log-level debug -ui-dir /ui
@ -112,9 +112,9 @@ And there, the same global configuration in the Key-value Store (using `prefix =
| `/traefik/consul/prefix` | `traefik` |
| `/traefik/web/address` | `:8081` |
In case you are setting key values manually,:
- 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`.
In case you are setting key values manually:
- 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.
@ -126,7 +126,7 @@ All the rest of the global configuration is stored in Consul.
Here is the [docker-compose file](https://docs.docker.com/compose/compose-file/) :
```yml
```yaml
traefik:
image: traefik
command: --consul --consul.endpoint=127.0.0.1:8500
@ -306,7 +306,7 @@ Don't forget to [setup the connection between Træfik and Key-value store](/user
The static Træfik configuration in a key-value store can be automatically created and updated, using the [`storeconfig` subcommand](/basics/#commands).
```bash
$ traefik storeconfig [flags] ...
$ traefik storeconfig [flags] ...
```
This command is here only to automate the [process which upload the configuration into the Key-value store](/user-guide/kv-config/#upload-the-configuration-in-the-key-value-store).
Træfik will not start but the [static configuration](/basics/#static-trfk-configuration) will be uploaded into the Key-value store.
@ -314,7 +314,7 @@ If you configured ACME (Let's Encrypt), your registration account and your certi
To upload your ACME certificates to the KV store, get your traefik TOML file and add the new `storage` option in the `acme` section:
```
```toml
[acme]
email = "test@traefik.io"
storage = "traefik/acme/account" # the key where to store your certificates in the KV store
@ -323,6 +323,7 @@ storageFile = "acme.json" # your old certificates store
Call `traefik storeconfig` to upload your config in the KV store.
Then remove the line `storageFile = "acme.json"` from your TOML config file.
That's it!
![](http://i.giphy.com/ujUdrdpX7Ok5W.gif)

28
docs/user-guide/swarm-mode.md
View file

@ -22,7 +22,7 @@ The cluster consists of:
First, let's create all the required nodes. It's a shorter version of
the [swarm tutorial](https://docs.docker.com/engine/swarm/swarm-tutorial/).
```sh
```shell
docker-machine create -d virtualbox manager
docker-machine create -d virtualbox worker1
docker-machine create -d virtualbox worker2
@ -34,7 +34,7 @@ Then, let's setup the cluster, in order :
2. get the token for other host to join
3. on both workers, join the cluster with the token
```sh
```shell
docker-machine ssh manager "docker swarm init \
--listen-addr $(docker-machine ip manager) \
--advertise-addr $(docker-machine ip manager)"
@ -57,7 +57,7 @@ docker-machine ssh worker2 "docker swarm join \
Let's validate the cluster is up and running.
```sh
```shell
docker-machine ssh manager docker node ls
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
2a770ov9vixeadep674265u1n worker1 Ready Active
@ -67,7 +67,7 @@ esbhhy6vnqv90xomjaomdgy46 worker2 Ready Active
Finally, let's create a network for Træfik to use.
```sh
```shell
docker-machine ssh manager "docker network create --driver=overlay traefik-net"
```
@ -79,7 +79,7 @@ on a manager node — we are going to use a
[constraint](https://docs.docker.com/engine/reference/commandline/service_create/#/specify-service-constraints-constraint) for
that.
```
```shell
docker-machine ssh manager "docker service create \
--name traefik \
--constraint=node.role==manager \
@ -115,7 +115,7 @@ We can now deploy our app on the cluster,
here [whoami](https://github.com/emilevauge/whoami), a simple web
server in Go. We start 2 services, on the `traefik-net` network.
```sh
```shell
docker-machine ssh manager "docker service create \
--name whoami0 \
--label traefik.port=80 \
@ -135,7 +135,7 @@ If using `docker stack deploy`, there is [a specific way that the labels must be
Check that everything is scheduled and started:
```sh
```shell
docker-machine ssh manager "docker service ls"
ID NAME REPLICAS IMAGE COMMAND
ab046gpaqtln whoami0 1/1 emilevauge/whoami
@ -145,7 +145,7 @@ dtpl249tfghc traefik 1/1 traefik --docker --docker.swarmmode
## Access to your apps through Træfik
```sh
```shell
curl -H Host:whoami0.traefik http://$(docker-machine ip manager)
Hostname: 8147a7746e7a
IP: 127.0.0.1
@ -186,7 +186,7 @@ X-Forwarded-Server: 8fbc39271b4c
Note that as Træfik is published, you can access it from any machine
and not only the manager.
```sh
```shell
curl -H Host:whoami0.traefik http://$(docker-machine ip worker1)
Hostname: 8147a7746e7a
IP: 127.0.0.1
@ -226,7 +226,7 @@ X-Forwarded-Server: 8fbc39271b4c
## Scale both services
```sh
```shell
docker-machine ssh manager "docker service scale whoami0=5"
docker-machine ssh manager "docker service scale whoami1=5"
@ -235,7 +235,7 @@ docker-machine ssh manager "docker service scale whoami1=5"
Check that we now have 5 replicas of each `whoami` service:
```sh
```shell
docker-machine ssh manager "docker service ls"
ID NAME REPLICAS IMAGE COMMAND
ab046gpaqtln whoami0 5/5 emilevauge/whoami
@ -245,7 +245,7 @@ dtpl249tfghc traefik 1/1 traefik --docker --docker.swarmmode
## Access to your whoami0 through Træfik multiple times.
Repeat the following command multiple times and note that the Hostname changes each time as Traefik load balances each request against the 5 tasks.
```sh
```shell
curl -H Host:whoami0.traefik http://$(docker-machine ip manager)
Hostname: 8147a7746e7a
IP: 127.0.0.1
@ -266,7 +266,7 @@ X-Forwarded-Server: 8fbc39271b4c
```
Do the same against whoami1.
```sh
```shell
curl -H Host:whoami1.traefik http://$(docker-machine ip manager)
Hostname: ba2c21488299
IP: 127.0.0.1
@ -303,5 +303,3 @@ Now open your browser and go to http://whoami1.traefik/
You will now see that stickyness is maintained.
![](http://i.giphy.com/ujUdrdpX7Ok5W.gif)

19
docs/user-guide/swarm.md
View file

@ -21,13 +21,13 @@ We first follow [this guide](https://docs.docker.com/engine/userguide/networking
This machine is the service registry of our cluster.
```sh
```shell
docker-machine create -d virtualbox mh-keystore
```
Then we install the service registry [Consul](https://consul.io) on this machine:
```sh
```shell
eval "$(docker-machine env mh-keystore)"
docker run -d \
-p "8500:8500" \
@ -39,7 +39,7 @@ docker run -d \
This machine is a swarm master and a swarm agent on it.
```sh
```shell
docker-machine create -d virtualbox \
--swarm --swarm-master \
--swarm-discovery="consul://$(docker-machine ip mh-keystore):8500" \
@ -52,7 +52,7 @@ docker-machine create -d virtualbox \
This machine have a swarm agent on it.
```sh
```shell
docker-machine create -d virtualbox \
--swarm \
--swarm-discovery="consul://$(docker-machine ip mh-keystore):8500" \
@ -65,7 +65,7 @@ docker-machine create -d virtualbox \
Create the overlay network on the swarm master:
```sh
```shell
eval $(docker-machine env --swarm mhs-demo0)
docker network create --driver overlay --subnet=10.0.9.0/24 my-net
```
@ -74,7 +74,7 @@ docker network create --driver overlay --subnet=10.0.9.0/24 my-net
Deploy Træfik:
```sh
```shell
docker $(docker-machine config mhs-demo0) run \
-d \
-p 80:80 -p 8080:8080 \
@ -110,7 +110,7 @@ Let's explain this command:
We can now deploy our app on the cluster, here [whoami](https://github.com/emilevauge/whoami), a simple web server in GO, on the network `my-net`:
```sh
```shell
eval $(docker-machine env --swarm mhs-demo0)
docker run -d --name=whoami0 --net=my-net --env="constraint:node==mhs-demo0" emilevauge/whoami
docker run -d --name=whoami1 --net=my-net --env="constraint:node==mhs-demo1" emilevauge/whoami
@ -118,7 +118,7 @@ docker run -d --name=whoami1 --net=my-net --env="constraint:node==mhs-demo1" emi
Check that everything is started:
```sh
```shell
docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
ba2c21488299 emilevauge/whoami "/whoamI" 8 seconds ago Up 9 seconds 80/tcp mhs-demo1/whoami1
@ -128,7 +128,7 @@ ba2c21488299 emilevauge/whoami "/whoamI" 8 seconds ago
## Access to your apps through Træfik
```sh
```shell
curl -H Host:whoami0.traefik http://$(docker-machine ip mhs-demo0)
Hostname: 8147a7746e7a
IP: 127.0.0.1
@ -167,4 +167,3 @@ X-Forwarded-Server: 8fbc39271b4c
```
![](http://i.giphy.com/ujUdrdpX7Ok5W.gif)