Traefik & Docker

    Attach labels to your containers and let Traefik do the rest!

    Configuring Docker & Deploying / Exposing Services

    Enabling the docker provider

    File (YAML)

    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

    Configuring Docker Swarm & Deploying / Exposing Services

    Enabling the docker provider (Swarm Mode)

    File (YAML)

    1. providers:
    2.   docker:
    3.     # endpoint: "tcp://127.0.0.1:2375"
    4.     # docker swarm mode (1.12+)
    5.     endpoint: "tcp://127.0.0.1:2377"
    6.     swarmMode: true

    File (TOML)

    1. [providers.docker]
    2.   # swarm classic (1.12-)
    3.   # endpoint = "tcp://127.0.0.1:2375"
    4.   # docker swarm mode (1.12+)
    5.   endpoint = "tcp://127.0.0.1:2377"
    6.   swarmMode = true

    CLI

    1. # swarm classic (1.12-)
    2. # --providers.docker.endpoint=tcp://127.0.0.1:2375
    3. # docker swarm mode (1.12+)
    4. --providers.docker.endpoint=tcp://127.0.0.1:2377
    5. --providers.docker.swarmMode=true

    Attach labels to services (not to containers) while in Swarm mode (in your docker compose file)

    1. version: "3"
    2. services:
    3.   my-container:
    4.     deploy:
    5.       labels:
    6.         - traefik.http.routers.my-container.rule=Host(`example.com`)
    7.         - 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+ ().

    Routing Configuration

    Labels

    • Labels are case insensitive.
    • The complete list of labels can be found in .

    Traefik creates, for each container, a corresponding 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 service assignment with labels

    With labels in a compose file

    1. labels:
    3.   # service myservice gets automatically assigned to router myproxy
    4.   - "traefik.http.services.myservice.loadbalancer.server.port=80"

    Automatic service creation and assignment with labels

    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`)"

    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 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 and middlewares overview for more information.

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

    traefik.http.routers.<router_name>.service

    See 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 for more information.

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

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

    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 for more information.

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

    traefik.http.routers.<router_name>.priority

    See priority for more information.

    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”).

    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 for more information.

    1. - "traefik.http.services.<service_name>[email protected]"

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

    See pass Host header for more information.

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

      See 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 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 for more information.

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

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

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

      See 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.responseforwarding.flushinterval

      See 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 named my-redirect, you’d write traefik.http.middlewares.my-redirect.redirectscheme.scheme=https.

      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.

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

      Declaring TCP Routers and Services

      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 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 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 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 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 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.terminationdelay

      See for more information.

      1. - "traefik.tcp.services.mytcpservice.loadbalancer.terminationdelay=100"

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

      See PROXY protocol for more information.

      1. - "traefik.tcp.services.mytcpservice.loadbalancer.proxyprotocol.version=1"

      UDP

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

      Declaring UDP Routers and Services

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

      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

        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.

        1. - "traefik.docker.lbswarm=true"

        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.