Traefik & Consul Catalog

A Story of Tags, Services & Instances

Rancher

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

Routing Configuration

tags

General

Traefik creates, for each consul Catalog service, a corresponding service 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(`mydomain.com`).

traefik.http.routers.<router_name>.rule

See rule for more information.

traefik.http.routers.myrouter.rule=Host(`mydomain.com`)
traefik.http.routers.<router_name>.entrypoints

See entry points for more information.

traefik.http.routers.myrouter.entrypoints=web,websecure
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 rule 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=foobar.com
traefik.http.routers.<router_name>.tls.domains[n].sans

See domains for more information.

traefik.http.routers.myrouter.tls.domains[0].sans=test.foobar.com,dev.foobar.com
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 
traefik.http.routers.myrouter.priority=42

Services

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.

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.passhostheader 
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=foobar.com
traefik.http.services.<service_name>.loadbalancer.healthcheck.interval

See health check for more information.

traefik.http.services.myservice.loadbalancer.healthcheck.interval=10
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.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=10
traefik.http.services.<service_name>.loadbalancer.sticky

See sticky sessions for more information.

traefik.http.services.myservice.loadbalancer.sticky=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.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

FlushInterval specifies the flush interval to flush to the client while copying the response body.

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

Declaring and Referencing a Middleware 
# ...
# Declaring a middleware
traefik.http.middlewares.my-redirect.redirectscheme.scheme=https
# Referencing a middleware
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.

TCP

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

Declaring TCP Routers and Services 
traefik.tcp.routers.my-router.rule=HostSNI(`my-host.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 consul service (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(`myhost.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=foobar.com
traefik.tcp.routers.<router_name>.tls.domains[n].sans

See domains for more information.

traefik.tcp.routers.mytcprouter.tls.domains[0].sans=test.foobar.com,dev.foobar.com
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

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

See termination delay for more information.

traefik.tcp.services.mytcpservice.loadbalancer.terminationdelay=100

Specific Provider Options

traefik.enable

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.

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.