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

Enhance documentation.

Browse source
This commit is contained in:
Ludovic Fernandez 2017-09-05 15:58:03 +02:00 • committed by Traefiker
parent 732d73dd43
commit b0a0e16136
21 changed files with 676 additions and 434 deletions
Download patch file Download diff file Expand all files Collapse all files

20
docs/user-guide/getting-started-with-docker-and-lets-encrypt.md → docs/user-guide/docker-and-lets-encrypt.md
View file

@ -18,18 +18,22 @@ In this example, we're going to use a single network called `web` where all cont
On the Docker host, run the following command:
`$ docker network create web`
```shell
docker network create web
```
Now, let's create a directory on the server where we will configure the rest of Traefik:
`$ mkdir -p /opt/traefik`
```shell
mkdir -p /opt/traefik
```
Within this directory, we're going to create 3 empty files:
```sh
$ touch /opt/traefik/docker-compose.yml
$ touch /opt/traefik/acme.json && chmod 600 /opt/traefik/acme.json
$ touch /opt/traefik/traefik.toml
```shell
touch /opt/traefik/docker-compose.yml
touch /opt/traefik/acme.json && chmod 600 /opt/traefik/acme.json
touch /opt/traefik/traefik.toml
```
The `docker-compose.yml` file will provide us with a simple, consistent and more importantly, a deterministic way to create Traefik.
@ -76,7 +80,7 @@ defaultEntryPoints = ["https","http"]
[entryPoints.http]
address = ":80"
[entryPoints.http.redirect]
entryPoint = "https"
entryPoint = "https"
[entryPoints.https]
address = ":443"
[entryPoints.https.tls]
@ -104,7 +108,7 @@ This is the minimum configuration required to do the following:
- Enable the Docker configuration backend and listen for container events on the Docker unix socket we've mounted earlier. However, **new containers will not be exposed by Traefik by default, we'll get into this in a bit!**
- Enable automatic request and configuration of SSL certificates using Let's Encrypt. These certificates will be stored in the `acme.json` file, which you can back-up yourself and store off-premises.
Alright, let's boot the container. From the `/opt/traefik` directory, run `$ docker-compose up -d` which will create and start the Traefik container.
Alright, let's boot the container. From the `/opt/traefik` directory, run `docker-compose up -d` which will create and start the Traefik container.
## Exposing Web Services to the Outside World

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

@ -112,6 +112,7 @@ And there, the same global configuration in the Key-value Store (using `prefix =
| `/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`.
@ -190,7 +191,7 @@ Here is the toml configuration we would like to store in the store :
[backends]
[backends.backend1]
[backends.backend1.circuitbreaker]
expression = "NetworkErrorRatio() > 0.5"
expression = "NetworkErrorRatio() > 0.5"
[backends.backend1.servers.server1]
url = "http://172.17.0.2:80"
weight = 10
@ -199,10 +200,10 @@ Here is the toml configuration we would like to store in the store :
weight = 1
[backends.backend2]
[backends.backend1.maxconn]
amount = 10
extractorfunc = "request.host"
amount = 10
extractorfunc = "request.host"
[backends.backend2.LoadBalancer]
method = "drr"
method = "drr"
[backends.backend2.servers.server1]
url = "http://172.17.0.4:80"
weight = 1
@ -225,7 +226,7 @@ Here is the toml configuration we would like to store in the store :
[frontends.frontend3]
entrypoints = ["http", "https"] # overrides defaultEntryPoints
backend = "backend2"
rule = "Path:/test"
rule = "Path:/test"
```
And there, the same dynamic configuration in a KV Store (using `prefix = "traefik"`):
@ -277,7 +278,10 @@ Træfik can watch the backends/frontends configuration changes and generate its
Note that only backends/frontends rules are dynamic, the rest of the Træfik 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æfik to read an intermediate configuration state despite judicious use of the `--providersThrottleDuration` flag. To solve this problem, Træfik supports a special key called `/traefik/alias`. If set, Træfik use the value as an alternative key prefix.
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æfik to read an intermediate configuration state despite judicious use of the `--providersThrottleDuration` flag.
To solve this problem, Træfik supports a special key called `/traefik/alias`.
If set, Træfik use the value as an alternative key prefix.
Given the key structure below, Træfik will use the `http://172.17.0.2:80` as its only backend (frontend keys have been omitted for brevity).
@ -287,7 +291,8 @@ Given the key structure below, Træfik will use the `http://172.17.0.2:80` as it
| `/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`:
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 |
|-------------------------------------------------------------------------|-----------------------------|
@ -299,7 +304,8 @@ When an atomic configuration change is required, you may write a new configurati
| `/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:
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 |
|-------------------------------------------------------------------------|-----------------------------|
@ -320,7 +326,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.

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

@ -1,8 +1,6 @@
# Docker Swarm (mode) cluster
This section explains how to create a multi-host docker cluster with
swarm mode using [docker-machine](https://docs.docker.com/machine) and
how to deploy Træfik on it.
This section explains how to create a multi-host docker cluster with swarm mode using [docker-machine](https://docs.docker.com/machine) and how to deploy Træfik on it.
The cluster consists of:
@ -59,6 +57,8 @@ Let's validate the cluster is up and running.
```shell
docker-machine ssh manager docker node ls
```
```
ID HOSTNAME STATUS AVAILABILITY MANAGER STATUS
2a770ov9vixeadep674265u1n worker1 Ready Active
dbi3or4q8ii8elbws70g4hkdh * manager Ready Active Leader
@ -129,6 +129,8 @@ Check that everything is scheduled and started:
```shell
docker-machine ssh manager "docker service ls"
```
```
ID NAME REPLICAS IMAGE COMMAND
ab046gpaqtln whoami0 1/1 emilevauge/whoami
cgfg5ifzrpgm whoami1 1/1 emilevauge/whoami
@ -139,6 +141,8 @@ dtpl249tfghc traefik 1/1 traefik --docker --docker.swarmmode
```shell
curl -H Host:whoami0.traefik http://$(docker-machine ip manager)
```
```yaml
Hostname: 8147a7746e7a
IP: 127.0.0.1
IP: ::1
@ -155,8 +159,11 @@ X-Forwarded-For: 192.168.99.1
X-Forwarded-Host: 10.0.9.3:80
X-Forwarded-Proto: http
X-Forwarded-Server: 8fbc39271b4c
```
```shell
curl -H Host:whoami1.traefik http://$(docker-machine ip manager)
```
```yaml
Hostname: ba2c21488299
IP: 127.0.0.1
IP: ::1
@ -179,6 +186,8 @@ Note that as Træfik is published, you can access it from any machine and not on
```shell
curl -H Host:whoami0.traefik http://$(docker-machine ip worker1)
```
```yaml
Hostname: 8147a7746e7a
IP: 127.0.0.1
IP: ::1
@ -195,8 +204,11 @@ X-Forwarded-For: 192.168.99.1
X-Forwarded-Host: 10.0.9.3:80
X-Forwarded-Proto: http
X-Forwarded-Server: 8fbc39271b4c
```
```shell
curl -H Host:whoami1.traefik http://$(docker-machine ip worker2)
```
```yaml
Hostname: ba2c21488299
IP: 127.0.0.1
IP: ::1
@ -228,6 +240,8 @@ Check that we now have 5 replicas of each `whoami` service:
```shell
docker-machine ssh manager "docker service ls"
```
```
ID NAME REPLICAS IMAGE COMMAND
ab046gpaqtln whoami0 5/5 emilevauge/whoami
cgfg5ifzrpgm whoami1 5/5 emilevauge/whoami
@ -239,6 +253,9 @@ Repeat the following command multiple times and note that the Hostname changes e
```shell
curl -H Host:whoami0.traefik http://$(docker-machine ip manager)
```
```yaml
Hostname: 8147a7746e7a
IP: 127.0.0.1
IP: ::1
@ -261,6 +278,9 @@ Do the same against whoami1:
```shell
curl -H Host:whoami1.traefik http://$(docker-machine ip manager)
```
```yaml
Hostname: ba2c21488299
IP: 127.0.0.1
IP: ::1
@ -278,17 +298,16 @@ X-Forwarded-Host: 10.0.9.4:80
X-Forwarded-Proto: http
X-Forwarded-Server: 8fbc39271b4c
```
Wait, I thought we added the sticky flag to whoami1? Traefik relies on a cookie to maintain stickyness so you'll need to test this with a browser.
Wait, I thought we added the sticky flag to `whoami1`? Traefik relies on a cookie to maintain stickyness so you'll need to test this with a browser.
First you need to add whoami1.traefik to your hosts file:
First you need to add `whoami1.traefik` to your hosts file:
```ssh
```shell
if [ -n "$(grep whoami1.traefik /etc/hosts)" ];
then
echo "whoami1.traefik already exists (make sure the ip is current)";
echo "whoami1.traefik already exists (make sure the ip is current)";
else
sudo -- sh -c -e "echo '$(docker-machine ip manager)\twhoami1.traefik'
>> /etc/hosts";
sudo -- sh -c -e "echo '$(docker-machine ip manager)\twhoami1.traefik' >> /etc/hosts";
fi
```

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

@ -120,6 +120,8 @@ Check that everything is started:
```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
8147a7746e7a emilevauge/whoami "/whoamI" 19 seconds ago Up 20 seconds 80/tcp mhs-demo0/whoami0
@ -130,6 +132,8 @@ ba2c21488299 emilevauge/whoami "/whoamI" 8 seconds ago
```shell
curl -H Host:whoami0.traefik http://$(docker-machine ip mhs-demo0)
```
```yaml
Hostname: 8147a7746e7a
IP: 127.0.0.1
IP: ::1
@ -146,8 +150,12 @@ X-Forwarded-For: 192.168.99.1
X-Forwarded-Host: 10.0.9.3:80
X-Forwarded-Proto: http
X-Forwarded-Server: 8fbc39271b4c
```
```shell
curl -H Host:whoami1.traefik http://$(docker-machine ip mhs-demo0)
```
```yaml
Hostname: ba2c21488299
IP: 127.0.0.1
IP: ::1