Traefik & Docker Swarm¶
A Story of Labels & Containers
Attach labels to your containers and let Traefik do the rest!
One of the best feature of Traefik is to delegate the routing configuration to the application level. With Docker Swarm, Traefik can leverage labels attached to a service to generate routing rules.
Labels & sensitive data
We recommend to not use labels to store sensitive data (certificates, credentials, etc). Instead, we recommend to store sensitive data in a safer storage (secrets, file, etc).
Configuration Examples¶
Configuring Docker Swarm & Deploying / Exposing one Service
Enabling the docker provider (Swarm Mode)
providers:
swarm:
# swarm classic (1.12-)
# endpoint: "tcp://127.0.0.1:2375"
# docker swarm mode (1.12+)
endpoint: "tcp://127.0.0.1:2377"
[providers.swarm]
# swarm classic (1.12-)
# endpoint = "tcp://127.0.0.1:2375"
# docker swarm mode (1.12+)
endpoint = "tcp://127.0.0.1:2377"
# swarm classic (1.12-)
# --providers.swarm.endpoint=tcp://127.0.0.1:2375
# docker swarm mode (1.12+)
--providers.swarm.endpoint=tcp://127.0.0.1:2377
Attach labels to services (not containers) while in Swarm mode (in your Docker compose file). When there is only one service, and the router does not specify a service, then that service is automatically assigned to the router.
version: "3"
services:
my-container:
deploy:
labels:
- traefik.http.routers.my-container.rule=Host(`example.com`)
- traefik.http.services.my-container-service.loadbalancer.server.port=8080
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).
Specify a Custom Port for the Container
Forward requests for http://example.com
to http://<private IP of container>:12345
:
version: "3"
services:
my-container:
# ...
deploy:
labels:
- traefik.http.routers.my-container.rule=Host(`example.com`)
- traefik.http.routers.my-container.service=my-service"
# Tell Traefik to use the port 12345 to connect to `my-container`
- traefik.http.services.my-service.loadbalancer.server.port=12345
Traefik Connecting to the Wrong Port: HTTP/502 Gateway Error
By default, Traefik uses the lowest exposed port of a container as detailed in Port Detection of the Swarm provider.
Setting the label traefik.http.services.xxx.loadbalancer.server.port
overrides this behavior.
Specifying more than one router and service per container
Forwarding requests to more than one port on a container requires referencing the service loadbalancer port definition using the service parameter on the router.
In this example, requests are forwarded for http://example-a.com
to http://<private IP of container>:8000
in addition to http://example-b.com
forwarding to http://<private IP of container>:9000
:
version: "3"
services:
my-container:
# ...
deploy:
labels:
- traefik.http.routers.www-router.rule=Host(`example-a.com`)
- traefik.http.routers.www-router.service=www-service
- traefik.http.services.www-service.loadbalancer.server.port=8000
- traefik.http.routers.admin-router.rule=Host(`example-b.com`)
- traefik.http.routers.admin-router.service=admin-service
- traefik.http.services.admin-service.loadbalancer.server.port=9000
Routing Configuration¶
Labels
- Labels are case-insensitive.
- The complete list of labels can be found in the reference page.
General¶
Traefik creates, for each container, a corresponding service and router.
The Service automatically gets a server per instance of the container,
and the router automatically gets a rule defined by defaultRule
(if no rule for it was defined in labels).
Service definition¶
In general when configuring a Traefik provider, a service assigned to one (or several) router(s) must be defined as well for the routing to be functional.
There are, however, exceptions when using label-based configurations:
- If a label defines a router (e.g. through a router Rule) and a label defines a service (e.g. implicitly through a loadbalancer server port value), but the router does not specify any service, then that service is automatically assigned to the router.
- If a label defines a router (e.g. through a router Rule) but no service is defined, then a service is automatically created and assigned to the router.
As one would expect, in either of these cases, if in addition a service is specified for the router, then that service is the one assigned, regardless of whether it actually is defined or whatever else other services are defined.
Automatic service assignment with labels
With labels in a compose file
labels:
- "traefik.http.routers.myproxy.rule=Host(`example.net`)"
# service myservice gets automatically assigned to router myproxy
- "traefik.http.services.myservice.loadbalancer.server.port=80"
Automatic service creation and assignment with labels
With labels in a compose file
labels:
# no service specified or defined and yet one gets automatically created
# and assigned to router myproxy.
- "traefik.http.routers.myproxy.rule=Host(`example.net`)"
Routers¶
To update the configuration of the Router automatically attached to the container,
add labels starting with traefik.http.routers.<name-of-your-choice>.
and followed by the option you want to change.
For example, to change the rule, you could add the label traefik.http.routers.my-container.rule=Host(`example.com`)
.
The character @
is not authorized in the router name <router_name>
.
traefik.http.routers.<router_name>.rule
See rule for more information.
- "traefik.http.routers.myrouter.rule=Host(`example.com`)"
traefik.http.routers.<router_name>.entrypoints
See entry points for more information.
- "traefik.http.routers.myrouter.entrypoints=ep1,ep2"
traefik.http.routers.<router_name>.middlewares
See middlewares and middlewares overview for more information.
- "traefik.http.routers.myrouter.middlewares=auth,prefix,cb"
traefik.http.routers.<router_name>.service
See service for more information.
- "traefik.http.routers.myrouter.service=myservice"
traefik.http.routers.<router_name>.tls
See tls for more information.
- "traefik.http.routers.myrouter.tls=true"
traefik.http.routers.<router_name>.tls.certresolver
See certResolver for more information.
- "traefik.http.routers.myrouter.tls.certresolver=myresolver"
traefik.http.routers.<router_name>.tls.domains[n].main
See domains for more information.
- "traefik.http.routers.myrouter.tls.domains[0].main=example.org"
traefik.http.routers.<router_name>.tls.domains[n].sans
See domains for more information.
- "traefik.http.routers.myrouter.tls.domains[0].sans=test.example.org,dev.example.org"
traefik.http.routers.<router_name>.tls.options
See options for more information.
- "traefik.http.routers.myrouter.tls.options=foobar"
traefik.http.routers.<router_name>.priority
See priority for more information.
- "traefik.http.routers.myrouter.priority=42"
Services¶
To update the configuration of the Service automatically attached to the container,
add labels starting with traefik.http.services.<name-of-your-choice>.
, followed by the option you want to change.
For example, to change the passHostHeader
behavior,
you'd add the label traefik.http.services.<name-of-your-choice>.loadbalancer.passhostheader=false
.
The character @
is not authorized in the service name <service_name>
.
traefik.http.services.<service_name>.loadbalancer.server.port
Registers a port. Useful when the container exposes multiples ports.
Mandatory for Docker Swarm (see the section "Port Detection with Docker Swarm").
- "traefik.http.services.myservice.loadbalancer.server.port=8080"
traefik.http.services.<service_name>.loadbalancer.server.scheme
Overrides the default scheme.
- "traefik.http.services.myservice.loadbalancer.server.scheme=http"
traefik.http.services.<service_name>.loadbalancer.serverstransport
Allows to reference a ServersTransport resource that is defined either with the File provider or the Kubernetes CRD one. See serverstransport for more information.
- "traefik.http.services.<service_name>.loadbalancer.serverstransport=foobar@file"
traefik.http.services.<service_name>.loadbalancer.passhostheader
See pass Host header for more information.
- "traefik.http.services.myservice.loadbalancer.passhostheader=true"
traefik.http.services.<service_name>.loadbalancer.healthcheck.headers.<header_name>
See health check for more information.
- "traefik.http.services.myservice.loadbalancer.healthcheck.headers.X-Foo=foobar"
traefik.http.services.<service_name>.loadbalancer.healthcheck.hostname
See health check for more information.
- "traefik.http.services.myservice.loadbalancer.healthcheck.hostname=example.org"
traefik.http.services.<service_name>.loadbalancer.healthcheck.interval
See health check for more information.
- "traefik.http.services.myservice.loadbalancer.healthcheck.interval=10s"
traefik.http.services.<service_name>.loadbalancer.healthcheck.path
See health check for more information.
- "traefik.http.services.myservice.loadbalancer.healthcheck.path=/foo"
traefik.http.services.<service_name>.loadbalancer.healthcheck.method
See health check for more information.
- "traefik.http.services.myservice.loadbalancer.healthcheck.method=foobar"
traefik.http.services.<service_name>.loadbalancer.healthcheck.status
See health check for more information.
- "traefik.http.services.myservice.loadbalancer.healthcheck.status=42"
traefik.http.services.<service_name>.loadbalancer.healthcheck.port
See health check for more information.
- "traefik.http.services.myservice.loadbalancer.healthcheck.port=42"
traefik.http.services.<service_name>.loadbalancer.healthcheck.scheme
See health check for more information.
- "traefik.http.services.myservice.loadbalancer.healthcheck.scheme=http"
traefik.http.services.<service_name>.loadbalancer.healthcheck.timeout
See health check for more information.
- "traefik.http.services.myservice.loadbalancer.healthcheck.timeout=10s"
traefik.http.services.<service_name>.loadbalancer.healthcheck.followredirects
See health check for more information.
- "traefik.http.services.myservice.loadbalancer.healthcheck.followredirects=true"
traefik.http.services.<service_name>.loadbalancer.sticky.cookie
See sticky sessions for more information.
- "traefik.http.services.myservice.loadbalancer.sticky.cookie=true"
traefik.http.services.<service_name>.loadbalancer.sticky.cookie.httponly
See sticky sessions for more information.
- "traefik.http.services.myservice.loadbalancer.sticky.cookie.httponly=true"
traefik.http.services.<service_name>.loadbalancer.sticky.cookie.name
See sticky sessions for more information.
- "traefik.http.services.myservice.loadbalancer.sticky.cookie.name=foobar"
traefik.http.services.<service_name>.loadbalancer.sticky.cookie.path
See sticky sessions for more information.
- "traefik.http.services.myservice.loadbalancer.sticky.cookie.path=/foobar"
traefik.http.services.<service_name>.loadbalancer.sticky.cookie.secure
See sticky sessions for more information.
- "traefik.http.services.myservice.loadbalancer.sticky.cookie.secure=true"
traefik.http.services.<service_name>.loadbalancer.sticky.cookie.samesite
See sticky sessions for more information.
- "traefik.http.services.myservice.loadbalancer.sticky.cookie.samesite=none"
traefik.http.services.<service_name>.loadbalancer.responseforwarding.flushinterval
See response forwarding for more information.
- "traefik.http.services.myservice.loadbalancer.responseforwarding.flushinterval=10"
Middleware¶
You can declare pieces of middleware using labels starting with traefik.http.middlewares.<name-of-your-choice>.
,
followed by the middleware type/options.
For example, to declare a middleware redirectscheme
named my-redirect
,
you'd write traefik.http.middlewares.my-redirect.redirectscheme.scheme=https
.
More information about available middlewares in the dedicated middlewares section.
The character @
is not authorized in the middleware name.
Declaring and Referencing a Middleware
services:
my-container:
# ...
deploy:
labels:
# Declaring a middleware
- traefik.http.middlewares.my-redirect.redirectscheme.scheme=https
# Referencing a middleware
- traefik.http.routers.my-container.middlewares=my-redirect
Conflicts in Declaration
If you declare multiple middleware with the same name but with different parameters, the middleware fails to be declared.
TCP¶
You can declare TCP Routers and/or Services using labels.
Declaring TCP Routers and Services
services:
my-container:
# ...
deploy:
labels:
- "traefik.tcp.routers.my-router.rule=HostSNI(`example.com`)"
- "traefik.tcp.routers.my-router.tls=true"
- "traefik.tcp.services.my-service.loadbalancer.server.port=4123"
TCP and HTTP
If you declare a TCP Router/Service, it will prevent Traefik from automatically creating an HTTP Router/Service (like it does by default if no TCP Router/Service is defined). You can declare both a TCP Router/Service and an HTTP Router/Service for the same container (but you have to do so manually).
TCP Routers¶
traefik.tcp.routers.<router_name>.entrypoints
See entry points for more information.
- "traefik.tcp.routers.mytcprouter.entrypoints=ep1,ep2"
traefik.tcp.routers.<router_name>.rule
See rule for more information.
- "traefik.tcp.routers.mytcprouter.rule=HostSNI(`example.com`)"
traefik.tcp.routers.<router_name>.service
See service for more information.
- "traefik.tcp.routers.mytcprouter.service=myservice"
traefik.tcp.routers.<router_name>.tls
See TLS for more information.
- "traefik.tcp.routers.mytcprouter.tls=true"
traefik.tcp.routers.<router_name>.tls.certresolver
See certResolver for more information.
- "traefik.tcp.routers.mytcprouter.tls.certresolver=myresolver"
traefik.tcp.routers.<router_name>.tls.domains[n].main
See domains for more information.
- "traefik.tcp.routers.mytcprouter.tls.domains[0].main=example.org"
traefik.tcp.routers.<router_name>.tls.domains[n].sans
See domains for more information.
- "traefik.tcp.routers.mytcprouter.tls.domains[0].sans=test.example.org,dev.example.org"
traefik.tcp.routers.<router_name>.tls.options
See options for more information.
- "traefik.tcp.routers.mytcprouter.tls.options=mysoptions"
traefik.tcp.routers.<router_name>.tls.passthrough
See TLS for more information.
- "traefik.tcp.routers.mytcprouter.tls.passthrough=true"
traefik.tcp.routers.<router_name>.priority
See priority for more information.
- "traefik.tcp.routers.myrouter.priority=42"
TCP Services¶
traefik.tcp.services.<service_name>.loadbalancer.server.port
Registers a port of the application.
- "traefik.tcp.services.mytcpservice.loadbalancer.server.port=423"
traefik.tcp.services.<service_name>.loadbalancer.server.tls
Determines whether to use TLS when dialing with the backend.
- "traefik.tcp.services.mytcpservice.loadbalancer.server.tls=true"
traefik.tcp.services.<service_name>.loadbalancer.proxyprotocol.version
See PROXY protocol for more information.
- "traefik.tcp.services.mytcpservice.loadbalancer.proxyprotocol.version=1"
traefik.tcp.services.<service_name>.loadbalancer.serverstransport
Allows to reference a ServersTransport resource that is defined either with the File provider or the Kubernetes CRD one. See serverstransport for more information.
- "traefik.tcp.services.<service_name>.loadbalancer.serverstransport=foobar@file"
UDP¶
You can declare UDP Routers and/or Services using labels.
Declaring UDP Routers and Services
services:
my-container:
# ...
deploy:
labels:
- "traefik.udp.routers.my-router.entrypoints=udp"
- "traefik.udp.services.my-service.loadbalancer.server.port=4123"
UDP and HTTP
If you declare a UDP Router/Service, it will prevent Traefik from automatically creating an HTTP Router/Service (like it does by default if no UDP Router/Service is defined). You can declare both a UDP Router/Service and an HTTP Router/Service for the same container (but you have to do so manually).
UDP Routers¶
traefik.udp.routers.<router_name>.entrypoints
See entry points for more information.
- "traefik.udp.routers.myudprouter.entrypoints=ep1,ep2"
traefik.udp.routers.<router_name>.service
See service for more information.
- "traefik.udp.routers.myudprouter.service=myservice"
UDP Services¶
traefik.udp.services.<service_name>.loadbalancer.server.port
Registers a port of the application.
- "traefik.udp.services.myudpservice.loadbalancer.server.port=423"
Specific Provider Options¶
traefik.enable
¶
- "traefik.enable=true"
You can tell Traefik to consider (or not) the container by setting traefik.enable
to true or false.
This option overrides the value of exposedByDefault
.
traefik.docker.network
¶
- "traefik.docker.network=mynetwork"
Overrides the default docker network to use for connections to the container.
If a container is linked to several networks, be sure to set the proper network name (you can check this with docker inspect <container_id>
),
otherwise it will randomly pick one (depending on how docker is returning them).
Warning
The Docker Swarm provider still uses the same per-container mechanism as the Docker provider, so therefore the label still uses the docker
keyword intentionally.
Warning
When deploying a stack from a compose file stack
, the networks defined are prefixed with stack
.
traefik.docker.lbswarm
¶
- "traefik.docker.lbswarm=true"
Enables Swarm's inbuilt load balancer (only relevant in Swarm Mode).
If you enable this option, Traefik will use the virtual IP provided by docker swarm instead of the containers IPs. Which means that Traefik will not perform any kind of load balancing and will delegate this task to swarm.
Warning
The Docker Swarm provider still uses the same per-container mechanism as the Docker provider, so therefore the label still uses the docker
keyword intentionally.