Project: Traefik (Orchestration & Management / API Gateway)
File: consul-catalog.md

title: "Traefik Consul Catalog Routing" description: "Learn how to use Consul Catalog as a provider for routing configurations in Traefik Proxy. Read the technical documentation." A Story of Tags, Services & Instances {: .subtitle } Attach tags to your services and let Traefik do the rest! !!! info "tags" tags are case insensitive. The complete list of tags can be found Traefik creates, for each consul Catalog service, a corresponding and . 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. 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`)```. ??? info "`traefik.http.routers.<router_name>.rule`" See for more information. ```yaml traefik.http.routers.myrouter.rule=Host(`example.com`) ``` ??? info "`traefik.http.routers.<router_name>.entrypoints`" See for more information. ```yaml traefik.http.routers.myrouter.entrypoints=web,websecure ``` ??? info "`traefik.http.routers.<router_name>.middlewares`" See and for more information. ```yaml traefik.http.routers.myrouter.middlewares=auth,prefix,cb ``` ??? info "`traefik.http.routers.<router_name>.service`" See for more information. ```yaml traefik.http.routers.myrouter.service=myservice ``` ??? info "`traefik.http.routers.<router_name>.tls`" See for more information. ```yaml traefik.http.routers.myrouter.tls=true ``` ??? info "`traefik.http.routers.<router_name>.tls.certresolver`" See for more information. ```yaml traefik.http.routers.myrouter.tls.certresolver=myresolver ``` ??? info "`traefik.http.routers.<router_name>.tls.domains[n].main`" See for more information. ```yaml traefik.http.routers.myrouter.tls.domains[0].main=example.org ``` ??? info "`traefik.http.routers.<router_name>.tls.domains[n].sans`" See for more information. ```yaml traefik.http.routers.myrouter.tls.domains[0].sans=test.example.org,dev.example.org ``` ??? info "`traefik.http.routers.<router_name>.tls.options`" See for more information. ```yaml traefik.http.routers.myrouter.tls.options=foobar ``` ??? info "`traefik.http.routers.<router_name>.priority`" See for more information. ```yaml 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`. ??? info "`traefik.http.services.<service_name>.loadbalancer.server.port`" Registers a port. Useful when the service exposes multiples ports. ```yaml traefik.http.services.myservice.loadbalancer.server.port=8080 ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.server.scheme`" Overrides the default scheme. ```yaml traefik.http.services.myservice.loadbalancer.server.scheme=http ``` ??? info "`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. ```yaml traefik.http.services.myservice.loadbalancer.serverstransport=foobar@file ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.passhostheader`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.passhostheader=true ``` ??? info "`traefik.http.services.<servicename>.loadbalancer.healthcheck.headers.<headername>`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.healthcheck.headers.X-Foo=foobar ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.hostname`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.healthcheck.hostname=example.org ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.interval`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.healthcheck.interval=10 ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.path`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.healthcheck.path=/foo ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.method`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.healthcheck.method=foobar ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.status`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.healthcheck.status=42 ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.port`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.healthcheck.port=42 ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.scheme`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.healthcheck.scheme=http ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.timeout`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.healthcheck.timeout=10 ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.healthcheck.followredirects`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.healthcheck.followredirects=true ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.sticky.cookie=true ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.httponly`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.sticky.cookie.httponly=true ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.name`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.sticky.cookie.name=foobar ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.secure`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.sticky.cookie.secure=true ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.samesite`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.sticky.cookie.samesite=none ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.sticky.cookie.maxage`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.sticky.cookie.maxage=42 ``` ??? info "`traefik.http.services.<service_name>.loadbalancer.responseforwarding.flushinterval`" See for more information. ```yaml traefik.http.services.myservice.loadbalancer.responseforwarding.flushinterval=10 ``` 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

??? example "Declaring and Referencing a Middleware" ```yaml traefik.http.middlewares.my-redirect.redirectscheme.scheme=https traefik.http.routers.my-service.middlewares=my-redirect ``` !!! warning "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. ??? example "Declaring TCP Routers and Services" ```yaml 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 ``` !!! warning "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). ??? info "`traefik.tcp.routers.<router_name>.entrypoints`" See for more information. ```yaml traefik.tcp.routers.mytcprouter.entrypoints=ep1,ep2 ``` ??? info "`traefik.tcp.routers.<router_name>.rule`" See for more information. ```yaml traefik.tcp.routers.mytcprouter.rule=HostSNI(`example.com`) ``` ??? info "`traefik.tcp.routers.<router_name>.service`" See for more information. ```yaml traefik.tcp.routers.mytcprouter.service=myservice ``` ??? info "`traefik.tcp.routers.<router_name>.tls`" See for more information. ```yaml traefik.tcp.routers.mytcprouter.tls=true ``` ??? info "`traefik.tcp.routers.<router_name>.tls.certresolver`" See for more information. ```yaml traefik.tcp.routers.mytcprouter.tls.certresolver=myresolver ``` ??? info "`traefik.tcp.routers.<router_name>.tls.domains[n].main`" See for more information. ```yaml traefik.tcp.routers.mytcprouter.tls.domains[0].main=example.org ``` ??? info "`traefik.tcp.routers.<router_name>.tls.domains[n].sans`" See for more information. ```yaml traefik.tcp.routers.mytcprouter.tls.domains[0].sans=test.example.org,dev.example.org ``` ??? info "`traefik.tcp.routers.<router_name>.tls.options`" See for more information. ```yaml traefik.tcp.routers.mytcprouter.tls.options=mysoptions ``` ??? info "`traefik.tcp.routers.<router_name>.tls.passthrough`" See for more information. ```yaml traefik.tcp.routers.mytcprouter.tls.passthrough=true ``` ??? info "`traefik.tcp.services.<service_name>.loadbalancer.server.port`" Registers a port of the application. ```yaml traefik.tcp.services.mytcpservice.loadbalancer.server.port=423 ``` ??? info "`traefik.tcp.services.<service_name>.loadbalancer.server.tls`" Determines whether to use TLS when dialing with the backend. ```yaml traefik.tcp.services.mytcpservice.loadbalancer.server.tls=true ``` ??? info "`traefik.tcp.services.<service_name>.loadbalancer.proxyprotocol.version`" See for more information. ```yaml traefik.tcp.services.mytcpservice.loadbalancer.proxyprotocol.version=1 ``` ??? info "`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 for more information. ```yaml traefik.tcp.services.myservice.loadbalancer.serverstransport=foobar@file ``` You can declare UDP Routers and/or Services using tags. ??? example "Declaring UDP Routers and Services" ```yaml traefik.udp.routers.my-router.entrypoints=udp traefik.udp.services.my-service.loadbalancer.server.port=4123 ``` !!! warning "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). ??? info "`traefik.udp.routers.<router_name>.entrypoints`" See for more information. ```yaml traefik.udp.routers.myudprouter.entrypoints=ep1,ep2 ``` ??? info "`traefik.udp.routers.<router_name>.service`" See for more information. ```yaml traefik.udp.routers.myudprouter.service=myservice ``` ??? info "`traefik.udp.services.<service_name>.loadbalancer.server.port`" Registers a port of the application. ```yaml traefik.udp.services.myudpservice.loadbalancer.server.port=423 ``` ```yaml 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`. ```yaml traefik.consulcatalog.connect=true ``` 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`. ```yaml 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 instance of a service, or a production one. For example if one does not want them to be part of the same load-balancer. Therefore, this option, which is meant to be provided as one of the values of the `canary_tags` field in the Nomad , allows Traefik to identify that the associated instance is a canary one. 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.