1
0
Fork 0

Merge branch 'v2.0' into v2.1

This commit is contained in:
Fernandez Ludovic 2019-12-02 18:20:29 +01:00
commit 89919dbe36
52 changed files with 677 additions and 336 deletions

View file

@ -7,6 +7,9 @@ A Story of Labels & Containers
Attach labels to your containers and let Traefik do the rest!
Traefik works with both [Docker (standalone) Engine](https://docs.docker.com/engine/)
and [Docker Swarm Mode](https://docs.docker.com/engine/swarm/).
!!! tip "The Quick Start Uses Docker"
If you haven't already, maybe you'd like to go through the [quick start](../getting-started/quick-start.md) that uses the docker provider!
@ -64,7 +67,7 @@ Attach labels to your containers and let Traefik do the rest!
```
```bash tab="CLI"
--providers.docker.endpoint="tcp://127.0.0.1:2375"
--providers.docker.endpoint=tcp://127.0.0.1:2375
--providers.docker.swarmMode=true
```
@ -80,15 +83,136 @@ Attach labels to your containers and let Traefik do the rest!
- traefik.http.services.my-container-service.loadbalancer.server.port=8080
```
!!! important "Labels in Docker Swarm Mode"
While in Swarm Mode, Traefik uses labels found on services, not on individual containers.
Therefore, if you use a compose file with Swarm Mode, labels should be defined in the `deploy` part of your service.
This behavior is only enabled for docker-compose version 3+ ([Compose file reference](https://docs.docker.com/compose/compose-file/#labels-1)).
## Routing Configuration
See the dedicated section in [routing](../routing/providers/docker.md).
When using Docker as a [provider](https://docs.traefik.io/providers/overview/),
Trafik uses [container labels](https://docs.docker.com/engine/reference/commandline/run/#set-metadata-on-container--l---label---label-file) to retrieve its routing configuration.
See the list of labels in the dedicated [routing](../routing/providers/docker.md) section.
### Routing Configuration with Labels
By default, Traefik watches for [container level labels](https://docs.docker.com/config/labels-custom-metadata/) on a standalone Docker Engine.
When using Docker Compose, labels are specified by the directive
[`labels`](https://docs.docker.com/compose/compose-file/#labels) from the
["services" objects](https://docs.docker.com/compose/compose-file/#service-configuration-reference).
!!! tip "Not Only Docker"
Please note that any tool like Nomad, Terraform, Ansible, etc.
that is able to define a Docker container with labels can work
with Traefik & the Docker provider.
### Port Detection
Traefik retrieves the private IP and port of containers from the Docker API.
Ports detection works as follows:
- If a container [exposes](https://docs.docker.com/engine/reference/builder/#expose) only one port,
then Traefik uses this port for private communication.
- If a container [exposes](https://docs.docker.com/engine/reference/builder/#expose) multiple ports,
or does not expose any port, then you must manually specify which port Traefik should use for communication
by using the label `traefik.http.services.<service_name>.loadbalancer.server.port`
(Read more on this label in the dedicated section in [routing](../routing/providers/docker.md#port)).
### Docker API Access
Traefik requires access to the docker socket to get its dynamic configuration.
You can specify which Docker API Endpoint to use with the directive [`endpoint`](#endpoint).
!!! warning "Security Note"
Accessing the Docker API without any restriction is a security concern:
If Traefik is attacked, then the attacker might get access to the underlying host.
{: #security-note }
As explained in the Docker documentation: ([Docker Daemon Attack Surface page](https://docs.docker.com/engine/security/security/#docker-daemon-attack-surface)):
!!! quote
[...] only **trusted** users should be allowed to control your Docker daemon [...]
??? success "Solutions"
Expose the Docker socket over TCP, instead of the default Unix socket file.
It allows different implementation levels of the [AAA (Authentication, Authorization, Accounting) concepts](https://en.wikipedia.org/wiki/AAA_(computer_security)), depending on your security assessment:
- Authentication with Client Certificates as described in ["Protect the Docker daemon socket."](https://docs.docker.com/engine/security/https/)
- Authorize and filter requests to restrict possible actions with [the TecnativaDocker Socket Proxy](https://github.com/Tecnativa/docker-socket-proxy).
- Authorization with the [Docker Authorization Plugin Mechanism](https://docs.docker.com/engine/extend/plugins_authorization/)
- Accounting at networking level, by exposing the socket only inside a Docker private network, only available for Traefik.
- Accounting at container level, by exposing the socket on a another container than Traefik's.
With Swarm mode, it allows scheduling of Traefik on worker nodes, with only the "socket exposer" container on the manager nodes.
- Accounting at kernel level, by enforcing kernel calls with mechanisms like [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux), to only allows an identified set of actions for Traefik's process (or the "socket exposer" process).
??? info "More Resources and Examples"
- ["Paranoid about mounting /var/run/docker.sock?"](https://medium.com/@containeroo/traefik-2-0-paranoid-about-mounting-var-run-docker-sock-22da9cb3e78c)
- [Traefik and Docker: A Discussion with Docker Captain, Bret Fisher](https://blog.containo.us/traefik-and-docker-a-discussion-with-docker-captain-bret-fisher-7f0b9a54ff88)
- [KubeCon EU 2018 Keynote, Running with Scissors, from Liz Rice](https://www.youtube.com/watch?v=ltrV-Qmh3oY)
- [Don't expose the Docker socket (not even to a container)](https://www.lvh.io/posts/dont-expose-the-docker-socket-not-even-to-a-container/)
- [A thread on Stack Overflow about sharing the `/var/run/docker.sock` file](https://news.ycombinator.com/item?id=17983623)
- [To DinD or not to DinD](https://blog.loof.fr/2018/01/to-dind-or-not-do-dind.html)
- [Traefik issue GH-4174 about security with Docker socket](https://github.com/containous/traefik/issues/4174)
- [Inspecting Docker Activity with Socat](https://developers.redhat.com/blog/2015/02/25/inspecting-docker-activity-with-socat/)
- [Letting Traefik run on Worker Nodes](https://blog.mikesir87.io/2018/07/letting-traefik-run-on-worker-nodes/)
- [Docker Socket Proxy from Tecnativa](https://github.com/Tecnativa/docker-socket-proxy)
## Docker Swarm Mode
To enable Docker Swarm (instead of standalone Docker) as a configuration provider,
set the [`swarmMode`](#swarmmode) directive to `true`.
### Routing Configuration with Labels
While in Swarm Mode, Traefik uses labels found on services, not on individual containers.
Therefore, if you use a compose file with Swarm Mode, labels should be defined in the
[`deploy`](https://docs.docker.com/compose/compose-file/#labels-1) part of your service.
This behavior is only enabled for docker-compose version 3+ ([Compose file reference](https://docs.docker.com/compose/compose-file)).
### Port Detection
Docker Swarm does not provide any [port detection](#port-detection) information to Traefik.
Therefore you **must** specify the port to use for communication by using the label `traefik.http.services.<service_name>.loadbalancer.server.port`
(Check the reference for this label in the [routing section for Docker](../routing/providers/docker.md#port)).
### Docker API Access
Docker Swarm Mode follows the same rules as Docker [API Access](#docker-api-access).
As the Swarm API is only exposed on the [manager nodes](https://docs.docker.com/engine/swarm/how-swarm-mode-works/nodes/#manager-nodes), you should schedule Traefik on the Swarm manager nodes by default,
by deploying Traefik with a [constraint](https://success.docker.com/article/using-contraints-and-labels-to-control-the-placement-of-containers) on the node's "role":
```shell tab="With Docker CLI"
docker service create \
--constraint=node.role==manager \
#... \
```
```yml tab="With Docker Compose"
version: '3'
services:
traefik:
# ...
deploy:
placement:
constraints:
- node.role == manager
```
!!! tip "Scheduling Traefik on Worker Nodes"
Following the guidelines given in the previous section ["Docker API Access"](#docker-api-access),
if you expose the Docker API through TCP, then Traefik can be scheduled on any node if the TCP
socket is reachable.
Please consider the security implications by reading the [Security Note](#security-note).
A good example can be found on [Bret Fisher's repository](https://github.com/BretFisher/dogvscat/blob/master/stack-proxy-global.yml#L124).
## Provider Configuration
@ -108,51 +232,10 @@ providers:
```
```bash tab="CLI"
--providers.docker.endpoint="unix:///var/run/docker.sock"
--providers.docker.endpoint=unix:///var/run/docker.sock
```
Traefik requires access to the docker socket to get its dynamic configuration.
??? warning "Security Notes"
Depending on your context, accessing the Docker API without any restriction can be a security concern: If Traefik is attacked, then the attacker might get access to the Docker (or Swarm Mode) backend.
As explained in the Docker documentation: ([Docker Daemon Attack Surface page](https://docs.docker.com/engine/security/security/#docker-daemon-attack-surface)):
`[...] only **trusted** users should be allowed to control your Docker daemon [...]`
!!! tip "Improved Security"
[TraefikEE](https://containo.us/traefikee) solves this problem by separating the control plane (connected to Docker) and the data plane (handling the requests).
??? info "Resources about Docker's Security"
- [KubeCon EU 2018 Keynote, Running with Scissors, from Liz Rice](https://www.youtube.com/watch?v=ltrV-Qmh3oY)
- [Don't expose the Docker socket (not even to a container)](https://www.lvh.io/posts/dont-expose-the-docker-socket-not-even-to-a-container/)
- [A thread on Stack Overflow about sharing the `/var/run/docker.sock` file](https://news.ycombinator.com/item?id=17983623)
- [To DinD or not to DinD](https://blog.loof.fr/2018/01/to-dind-or-not-do-dind.html)
??? tip "Security Compensation"
Expose the Docker socket over TCP, instead of the default Unix socket file.
It allows different implementation levels of the [AAA (Authentication, Authorization, Accounting) concepts](https://en.wikipedia.org/wiki/AAA_(computer_security)), depending on your security assessment:
- Authentication with Client Certificates as described in ["Protect the Docker daemon socket."](https://docs.docker.com/engine/security/https/)
- Authorization with the [Docker Authorization Plugin Mechanism](https://docs.docker.com/engine/extend/plugins_authorization/)
- Accounting at networking level, by exposing the socket only inside a Docker private network, only available for Traefik.
- Accounting at container level, by exposing the socket on a another container than Traefik's.
With Swarm mode, it allows scheduling of Traefik on worker nodes, with only the "socket exposer" container on the manager nodes.
- Accounting at kernel level, by enforcing kernel calls with mechanisms like [SELinux](https://en.wikipedia.org/wiki/Security-Enhanced_Linux), to only allows an identified set of actions for Traefik's process (or the "socket exposer" process).
??? info "Additional Resources"
- [Traefik issue GH-4174 about security with Docker socket](https://github.com/containous/traefik/issues/4174)
- [Inspecting Docker Activity with Socat](https://developers.redhat.com/blog/2015/02/25/inspecting-docker-activity-with-socat/)
- [Letting Traefik run on Worker Nodes](https://blog.mikesir87.io/2018/07/letting-traefik-run-on-worker-nodes/)
- [Docker Socket Proxy from Tecnativa](https://github.com/Tecnativa/docker-socket-proxy)
!!! info "Traefik & Swarm Mode"
To let Traefik access the Docker Socket of the Swarm manager, it is mandatory to schedule Traefik on the Swarm manager nodes.
See the sections [Docker API Access](#docker-api-access) and [Docker Swarm API Access](#docker-api-access_1) for more information.
??? example "Using the docker.sock"
@ -186,7 +269,7 @@ Traefik requires access to the docker socket to get its dynamic configuration.
```
```bash tab="CLI"
--providers.docker.endpoint="unix:///var/run/docker.sock"
--providers.docker.endpoint=unix:///var/run/docker.sock
# ...
```
@ -311,7 +394,7 @@ providers:
```
```bash tab="CLI"
--providers.docker.defaultRule="Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
--providers.docker.defaultRule=Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)
# ...
```
@ -343,7 +426,7 @@ providers:
# ...
```
Activates the Swarm Mode.
Activates the Swarm Mode (instead of standalone Docker).
### `swarmModeRefreshSeconds`
@ -375,19 +458,19 @@ _Optional, Default=""_
```toml tab="File (TOML)"
[providers.docker]
constraints = "Label(`a.label.name`, `foo`)"
constraints = "Label(`a.label.name`,`foo`)"
# ...
```
```yaml tab="File (YAML)"
providers:
docker:
constraints: "Label(`a.label.name`, `foo`)"
constraints: "Label(`a.label.name`,`foo`)"
# ...
```
```bash tab="CLI"
--providers.docker.constraints="Label(`a.label.name`, `foo`)"
--providers.docker.constraints=Label(`a.label.name`,`foo`)
# ...
```

View file

@ -32,7 +32,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetescrd.endpoint="http://localhost:8080"
--providers.kubernetescrd.endpoint=http://localhost:8080
```
The Kubernetes server endpoint as URL.
@ -66,7 +66,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetescrd.token="mytoken"
--providers.kubernetescrd.token=mytoken
```
Bearer token used for the Kubernetes client configuration.
@ -89,7 +89,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetescrd.certauthfilepath="/my/ca.crt"
--providers.kubernetescrd.certauthfilepath=/my/ca.crt
```
Path to the certificate authority file.
@ -115,7 +115,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetescrd.namespaces="default,production"
--providers.kubernetescrd.namespaces=default,production
```
Array of namespaces to watch.
@ -164,7 +164,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetescrd.ingressclass="traefik-internal"
--providers.kubernetescrd.ingressclass=traefik-internal
```
Value of `kubernetes.io/ingress.class` annotation that identifies Ingress objects to be processed.
@ -190,7 +190,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetescrd.throttleDuration="10s"
--providers.kubernetescrd.throttleDuration=10s
```
## Further

View file

@ -67,7 +67,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetesingress.endpoint="http://localhost:8080"
--providers.kubernetesingress.endpoint=http://localhost:8080
```
The Kubernetes server endpoint as URL, which is only used when the behavior based on environment variables described below does not apply.
@ -99,7 +99,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetesingress.token="mytoken"
--providers.kubernetesingress.token=mytoken
```
Bearer token used for the Kubernetes client configuration.
@ -122,7 +122,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetesingress.certauthfilepath="/my/ca.crt"
--providers.kubernetesingress.certauthfilepath=/my/ca.crt
```
Path to the certificate authority file.
@ -171,7 +171,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetesingress.namespaces="default,production"
--providers.kubernetesingress.namespaces=default,production
```
Array of namespaces to watch.
@ -220,7 +220,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetesingress.ingressclass="traefik-internal"
--providers.kubernetesingress.ingressclass=traefik-internal
```
Value of `kubernetes.io/ingress.class` annotation that identifies Ingress objects to be processed.
@ -249,7 +249,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetesingress.ingressendpoint.hostname="foo.com"
--providers.kubernetesingress.ingressendpoint.hostname=foo.com
```
Hostname used for Kubernetes Ingress endpoints.
@ -273,7 +273,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetesingress.ingressendpoint.ip="1.2.3.4"
--providers.kubernetesingress.ingressendpoint.ip=1.2.3.4
```
IP used for Kubernetes Ingress endpoints.
@ -297,7 +297,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetesingress.ingressendpoint.publishedservice="foo-service"
--providers.kubernetesingress.ingressendpoint.publishedservice=foo-service
```
Published Kubernetes Service to copy status from.
@ -320,7 +320,7 @@ providers:
```
```bash tab="CLI"
--providers.kubernetesingress.throttleDuration="10s"
--providers.kubernetesingress.throttleDuration=10s
```
## Further

View file

@ -74,8 +74,8 @@ providers:
```
```bash tab="CLI"
--providers.marathon.basic.httpbasicauthuser="foo"
--providers.marathon.basic.httpbasicpassword="bar"
--providers.marathon.basic.httpbasicauthuser=foo
--providers.marathon.basic.httpbasicpassword=bar
```
Enables Marathon basic authentication.
@ -98,7 +98,7 @@ providers:
```
```bash tab="CLI"
--providers.marathon.dcosToken="xxxxxx"
--providers.marathon.dcosToken=xxxxxx
```
DCOSToken for DCOS environment.
@ -123,7 +123,7 @@ providers:
```
```bash tab="CLI"
--providers.marathon.defaultRule="Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
--providers.marathon.defaultRule=Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)
# ...
```
@ -182,7 +182,7 @@ providers:
```
```bash tab="CLI"
--providers.marathon.endpoint="http://10.241.1.71:8080,10.241.1.72:8080,10.241.1.73:8080"
--providers.marathon.endpoint=http://10.241.1.71:8080,10.241.1.72:8080,10.241.1.73:8080
```
Marathon server endpoint.
@ -223,19 +223,19 @@ _Optional, Default=""_
```toml tab="File (TOML)"
[providers.marathon]
constraints = "Label(`a.label.name`, `foo`)"
constraints = "Label(`a.label.name`,`foo`)"
# ...
```
```yaml tab="File (YAML)"
providers:
marathon:
constraints: "Label(`a.label.name`, `foo`)"
constraints: "Label(`a.label.name`,`foo`)"
# ...
```
```bash tab="CLI"
--providers.marathon.constraints="Label(`a.label.name`, `foo`)"
--providers.marathon.constraints=Label(`a.label.name`,`foo`)
# ...
```
@ -389,7 +389,7 @@ providers:
```
```bash tab="CLI"
--providers.marathon.responseHeaderTimeout="66s"
--providers.marathon.responseHeaderTimeout=66s
# ...
```
@ -532,7 +532,7 @@ providers:
```
```bash tab="CLI"
--providers.marathon.responseHeaderTimeout="10s"
--providers.marathon.responseHeaderTimeout=10s
# ...
```

View file

@ -104,7 +104,7 @@ providers:
```
```bash tab="CLI"
--providers.rancher.defaultRule="Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
--providers.rancher.defaultRule=Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)
# ...
```
@ -209,7 +209,7 @@ providers:
```
```bash tab="CLI"
--providers.rancher.prefix="/test"
--providers.rancher.prefix=/test
# ...
```
@ -221,19 +221,19 @@ _Optional, Default=""_
```toml tab="File (TOML)"
[providers.rancher]
constraints = "Label(`a.label.name`, `foo`)"
constraints = "Label(`a.label.name`,`foo`)"
# ...
```
```yaml tab="File (YAML)"
providers:
rancher:
constraints: "Label(`a.label.name`, `foo`)"
constraints: "Label(`a.label.name`,`foo`)"
# ...
```
```bash tab="CLI"
--providers.rancher.constraints="Label(`a.label.name`, `foo`)"
--providers.rancher.constraints=Label(`a.label.name`,`foo`)
# ...
```

View file

@ -17,4 +17,4 @@
--providers.rancher.intervalPoll=false
# Prefix used for accessing the Rancher metadata service
--providers.rancher.prefix="/latest"
--providers.rancher.prefix=/latest

View file

@ -18,4 +18,4 @@ providers:
intervalPoll: false
# Prefix used for accessing the Rancher metadata service
prefix: "/latest"
prefix: /latest