Traefik & Consul Catalog

    Attach tags to your services and let Traefik do the rest!

    tags

    • tags are case insensitive.
    • The complete list of tags can be found

    Traefik creates, for each consul Catalog service, a corresponding and router.

    The Service automatically gets a server per instance in this consul Catalog service, and the router gets a default rule attached to it, based on the service name.

    Routers

    To update the configuration of the Router automatically attached to the service, add tags starting with traefik.routers.{name-of-your-choice}. and followed by the option you want to change.

    For example, to change the rule, you could add the tag traefik.http.routers.my-service.rule=Host(`example.com`).

    traefik.http.routers.<router_name>.rule

    See rule for more information.

    traefik.http.routers.<router_name>.entrypoints

    See for more information.

    1. traefik.http.routers.myrouter.entrypoints=web,websecure

    traefik.http.routers.<router_name>.middlewares

    See middlewares and for more information.

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

    traefik.http.routers.<router_name>.service

    See rule for more information.

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

    traefik.http.routers.<router_name>.tls

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

      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.

      1. traefik.http.routers.myrouter.priority=42

      To update the configuration of the Service automatically attached to the service, add tags 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 tag traefik.http.services.{name-of-your-choice}.loadbalancer.passhostheader=false.

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

      Registers a port. Useful when the service 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. traef[email protected]file

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

      See for more information.

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

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

      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

      See for more information.

      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=10

      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.

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

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

      More information about available middlewares in the dedicated middlewares section.

      Declaring and Referencing a Middleware

      1. # ...
      2. # Declaring a middleware
      3. # Referencing a middleware
      4. traefik.http.routers.my-service.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 tags.

      Declaring TCP Routers and Services

      1. traefik.tcp.routers.my-router.rule=HostSNI(`example.com`)
      2. traefik.tcp.routers.my-router.tls=true
      3. 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 consul service (but you have to do so manually).

      TCP Routers

      See for more information.

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

      traefik.tcp.routers.<router_name>.rule

      See rule for more information.

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

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

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

      Declaring UDP Routers and Services

      1. traefik.udp.routers.my-router.entrypoints=udp
      2. 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 consul service (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 service by setting traefik.enable to true or false.

      This option overrides the value of exposedByDefault.

      traefik.consulcatalog.connect

      You can tell Traefik to consider (or not) the service as a Connect capable one by setting traefik.consulcatalog.connect to true or false.

      This option overrides the value of connectByDefault.

      traefik.consulcatalog.canary

      1. traefik.consulcatalog.canary=true

      When ConsulCatalog, in the context of a Nomad orchestrator, is a provider (of service registration) for Traefik, one might have the need to distinguish within Traefik between a Canary instance of a service, or a production one. For example if one does not want them to be part of the same load-balancer.

      Port Lookup

      Traefik is capable of detecting the port to use, by following the default consul Catalog flow. That means, if you just expose lets say port :1337 on the consul Catalog ui, traefik will pick up this port and use it.