Traefik & Docker

A Story of Labels & Containers

Docker

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, Traefik can leverage labels attached to a container 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 & Deploying / Exposing one Service

Enabling the docker provider

File (YAML)

  1. providers:
  2.   docker: {}

File (TOML)

  1. [providers.docker]

CLI

  1. --providers.docker=true

Attaching labels to containers (in your docker compose file)

  1. version: "3"
  2. services:
  3.   my-container:
  4.     # ...
  5.     labels:
  6.       - traefik.http.routers.my-container.rule=Host(`example.com`)

Specify a Custom Port for the Container

Forward requests for http://example.com to http://<private IP of container>:12345:

  1. version: "3"
  2. services:
  3.   my-container:
  4.     # ...
  5.     labels:
  6.       - traefik.http.routers.my-container.rule=Host(`example.com`)
  7.       # Tell Traefik to use the port 12345 to connect to `my-container`
  8.       - traefik.http.services.my-service.loadbalancer.server.port=12345

Traefik Connecting to the Wrong Port: HTTP/502 Gateway Error

By default, Traefik uses the first exposed port of a container.

Setting the label traefik.http.services.xxx.loadbalancer.server.port overrides that 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:

  1. version: "3"
  2. services:
  3.   my-container:
  4.     # ...
  5.     labels:
  6.       - traefik.http.routers.www-router.rule=Host(`example-a.com`)
  7.       - traefik.http.routers.www-router.service=www-service
  8.       - traefik.http.services.www-service.loadbalancer.server.port=8000
  9.       - traefik.http.routers.admin-router.rule=Host(`example-b.com`)
  10.       - traefik.http.routers.admin-router.service=admin-service
  11.       - 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:

  1. 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.
  2. 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 assignment with one Service

With labels in a compose file

  1. labels:
  2.   - "traefik.http.routers.myproxy.rule=Host(`example.net`)"
  3.   # service myservice gets automatically assigned to router myproxy
  4.   - "traefik.http.services.myservice.loadbalancer.server.port=80"

Automatic service creation with one Router

With labels in a compose file

  1. labels:
  2.   # no service specified or defined and yet one gets automatically created
  3.   # and assigned to router myproxy.
  4.   - "traefik.http.routers.myproxy.rule=Host(`example.net`)"

Explicit definition with one Service

With labels in a compose file

  1. labels:
  2.   - traefik.http.routers.www-router.rule=Host(`example-a.com`)
  3.   # Explicit link between the router and the service
  4.   - traefik.http.routers.www-router.service=www-service
  5.   - traefik.http.services.www-service.loadbalancer.server.port=8000

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.

  1. - "traefik.http.routers.myrouter.rule=Host(`example.com`)"

traefik.http.routers.<router_name>.entrypoints

See entry points for more information.

  1. - "traefik.http.routers.myrouter.entrypoints=ep1,ep2"

traefik.http.routers.<router_name>.middlewares

See middlewares and middlewares overview for more information.

  1. - "traefik.http.routers.myrouter.middlewares=auth,prefix,cb"

traefik.http.routers.<router_name>.service

See service for more information.

  1. - "traefik.http.routers.myrouter.service=myservice"

traefik.http.routers.<router_name>.tls

See tls for more information.

  1. - "traefik.http.routers.myrouter.tls=true"

traefik.http.routers.<router_name>.tls.certresolver

See certResolver for more information.

  1. - "traefik.http.routers.myrouter.tls.certresolver=myresolver"

traefik.http.routers.<router_name>.tls.domains[n].main

See domains for more information.

  1. - "traefik.http.routers.myrouter.tls.domains[0].main=example.org"

traefik.http.routers.<router_name>.tls.domains[n].sans

See domains for more information.

  1. - "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.

  1. - "traefik.http.routers.myrouter.tls.options=foobar"

traefik.http.routers.<router_name>.priority

See priority for more information.

  1. - "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.

  1. - "traefik.http.services.myservice.loadbalancer.server.port=8080"

traefik.http.services.<service_name>.loadbalancer.server.scheme

Overrides the default scheme.

  1. - "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.

  1. - "traefik.http.services.<service_name>.loadbalancer.serverstransport=foobar@file"

traefik.http.services.<service_name>.loadbalancer.passhostheader

See pass Host header for more information.

  1. - "traefik.http.services.myservice.loadbalancer.passhostheader=true"

traefik.http.services.<service_name>.loadbalancer.healthcheck.headers.<header_name>

See health check for more information.

  1. - "traefik.http.services.myservice.loadbalancer.healthcheck.headers.X-Foo=foobar"

traefik.http.services.<service_name>.loadbalancer.healthcheck.hostname

See health check for more information.

  1. - "traefik.http.services.myservice.loadbalancer.healthcheck.hostname=example.org"

traefik.http.services.<service_name>.loadbalancer.healthcheck.interval

See health check for more information.

  1. - "traefik.http.services.myservice.loadbalancer.healthcheck.interval=10s"

traefik.http.services.<service_name>.loadbalancer.healthcheck.path

See health check for more information.

  1. - "traefik.http.services.myservice.loadbalancer.healthcheck.path=/foo"

traefik.http.services.<service_name>.loadbalancer.healthcheck.method

See health check for more information.

  1. - "traefik.http.services.myservice.loadbalancer.healthcheck.method=foobar"

traefik.http.services.<service_name>.loadbalancer.healthcheck.status

See health check for more information.

  1. - "traefik.http.services.myservice.loadbalancer.healthcheck.status=42"

traefik.http.services.<service_name>.loadbalancer.healthcheck.port

See health check for more information.

  1. - "traefik.http.services.myservice.loadbalancer.healthcheck.port=42"

traefik.http.services.<service_name>.loadbalancer.healthcheck.scheme

See health check for more information.

  1. - "traefik.http.services.myservice.loadbalancer.healthcheck.scheme=http"

traefik.http.services.<service_name>.loadbalancer.healthcheck.timeout

See health check for more information.

  1. - "traefik.http.services.myservice.loadbalancer.healthcheck.timeout=10s"

traefik.http.services.<service_name>.loadbalancer.healthcheck.followredirects

See health check for more information.

  1. - "traefik.http.services.myservice.loadbalancer.healthcheck.followredirects=true"

traefik.http.services.<service_name>.loadbalancer.sticky.cookie

See sticky sessions for more information.

  1. - "traefik.http.services.myservice.loadbalancer.sticky.cookie=true"

traefik.http.services.<service_name>.loadbalancer.sticky.cookie.httponly

See sticky sessions for more information.

  1. - "traefik.http.services.myservice.loadbalancer.sticky.cookie.httponly=true"

traefik.http.services.<service_name>.loadbalancer.sticky.cookie.name

See sticky sessions for more information.

  1. - "traefik.http.services.myservice.loadbalancer.sticky.cookie.name=foobar"

traefik.http.services.<service_name>.loadbalancer.sticky.cookie.secure

See sticky sessions for more information.

  1. - "traefik.http.services.myservice.loadbalancer.sticky.cookie.secure=true"

traefik.http.services.<service_name>.loadbalancer.sticky.cookie.samesite

See sticky sessions for more information.

  1. - "traefik.http.services.myservice.loadbalancer.sticky.cookie.samesite=none"

traefik.http.services.<service_name>.loadbalancer.sticky.cookie.maxage

See sticky sessions for more information.

  1. - "traefik.http.services.myservice.loadbalancer.sticky.cookie.maxage=42"

traefik.http.services.<service_name>.loadbalancer.responseforwarding.flushinterval

See response forwarding for more information.

  1. - "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

  1.    services:
  2.      my-container:
  3.        # ...
  4.        labels:
  5.          # Declaring a middleware
  6.          - traefik.http.middlewares.my-redirect.redirectscheme.scheme=https
  7.          # Referencing a middleware
  8.          - 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 with one Service

  1.    services:
  2.      my-container:
  3.        # ...
  4.        labels:
  5.          - "traefik.tcp.routers.my-router.rule=HostSNI(`example.com`)"
  6.          - "traefik.tcp.routers.my-router.tls=true"
  7.          - "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.

  1. - "traefik.tcp.routers.mytcprouter.entrypoints=ep1,ep2"

traefik.tcp.routers.<router_name>.rule

See rule for more information.

  1. - "traefik.tcp.routers.mytcprouter.rule=HostSNI(`example.com`)"

traefik.tcp.routers.<router_name>.service

See service for more information.

  1. - "traefik.tcp.routers.mytcprouter.service=myservice"

traefik.tcp.routers.<router_name>.tls

See TLS for more information.

  1. - "traefik.tcp.routers.mytcprouter.tls=true"

traefik.tcp.routers.<router_name>.tls.certresolver

See certResolver for more information.

  1. - "traefik.tcp.routers.mytcprouter.tls.certresolver=myresolver"

traefik.tcp.routers.<router_name>.tls.domains[n].main

See domains for more information.

  1. - "traefik.tcp.routers.mytcprouter.tls.domains[0].main=example.org"

traefik.tcp.routers.<router_name>.tls.domains[n].sans

See domains for more information.

  1. - "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.

  1. - "traefik.tcp.routers.mytcprouter.tls.options=mysoptions"

traefik.tcp.routers.<router_name>.tls.passthrough

See TLS for more information.

  1. - "traefik.tcp.routers.mytcprouter.tls.passthrough=true"

traefik.tcp.routers.<router_name>.priority

See priority for more information.

  1. - "traefik.tcp.routers.myrouter.priority=42"

TCP Services

traefik.tcp.services.<service_name>.loadbalancer.server.port

Registers a port of the application.

  1. - "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.

  1. - "traefik.tcp.services.mytcpservice.loadbalancer.server.tls=true"

traefik.tcp.services.<service_name>.loadbalancer.proxyprotocol.version

See PROXY protocol for more information.

  1. - "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.

  1. - "traefik.tcp.services.<service_name>.loadbalancer.serverstransport=foobar@file"

UDP

You can declare UDP Routers and/or Services using labels.

Declaring UDP Routers with one Service

  1.    services:
  2.      my-container:
  3.        # ...
  4.        labels:
  5.          - "traefik.udp.routers.my-router.entrypoints=udp"
  6.          - "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.

  1. - "traefik.udp.routers.myudprouter.entrypoints=ep1,ep2"

traefik.udp.routers.<router_name>.service

See service for more information.

  1. - "traefik.udp.routers.myudprouter.service=myservice"

UDP Services

traefik.udp.services.<service_name>.loadbalancer.server.port

Registers a port of the application.

  1. - "traefik.udp.services.myudpservice.loadbalancer.server.port=423"

Specific Provider Options

traefik.enable

  1. - "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

  1. - "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

When deploying a stack from a compose file stack, the networks defined are prefixed with stack.