Traefik & Consul Catalog

A Story of Tags, Services & Instances

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

Configuration Examples

Configuring Consul Catalog & Deploying / Exposing Services

Enabling the consul catalog provider

File (YAML)

providers:
  consulCatalog: {}

File (TOML)

[providers.consulCatalog]

CLI

--providers.consulcatalog=true

Attaching tags to services

- traefik.http.routers.my-router.rule=Host(`example.com`)

Routing Configuration

See the dedicated section in routing.

Provider Configuration

refreshInterval

Optional, Default=15s

Defines the polling interval.

File (YAML)

providers:
  consulCatalog:
    refreshInterval: 30s
    # ...

File (TOML)

[providers.consulCatalog]
  refreshInterval = "30s"
  # ...

CLI

--providers.consulcatalog.refreshInterval=30s
# ...

prefix

required, Default=”traefik”

The prefix for Consul Catalog tags defining Traefik labels.

File (YAML)

providers:
  consulCatalog:
    prefix: test
    # ...

File (TOML)

[providers.consulCatalog]
  prefix = "test"
  # ...

CLI

--providers.consulcatalog.prefix=test
# ...

requireConsistent

Optional, Default=false

Forces the read to be fully consistent.

It is more expensive due to an extra round-trip but prevents ever performing a stale read.

For more information, see the consul documentation on consistency.

File (YAML)

providers:
  consulCatalog:
    requireConsistent: true
    # ...

File (TOML)

[providers.consulCatalog]
  requireConsistent = true
  # ...

CLI

--providers.consulcatalog.requireConsistent=true
# ...

stale

Optional, Default=false

Use stale consistency for catalog reads.

This makes reads very fast and scalable at the cost of a higher likelihood of stale values.

For more information, see the consul documentation on consistency.

File (YAML)

providers:
  consulCatalog:
    stale: true
    # ...

File (TOML)

[providers.consulCatalog]
  stale = true
  # ...

CLI

--providers.consulcatalog.stale=true
# ...

cache

Optional, Default=false

Use local agent caching for catalog reads.

File (YAML)

providers:
  consulCatalog:
    cache: true
    # ...

File (TOML)

[providers.consulCatalog]
  cache = true
  # ...

CLI

--providers.consulcatalog.cache=true
# ...

endpoint

Defines the Consul server endpoint.

address

Defines the address of the Consul server.

Optional, Default=”127.0.0.1:8500”

File (YAML)

providers:
  consulCatalog:
    endpoint:
      address: 127.0.0.1:8500
    # ...

File (TOML)

[providers.consulCatalog]
  [providers.consulCatalog.endpoint]
    address = "127.0.0.1:8500"
    # ...

CLI

--providers.consulcatalog.endpoint.address=127.0.0.1:8500
# ...

scheme

Optional, Default=””

Defines the URI scheme for the Consul server.

File (YAML)

providers:
  consulCatalog:
    endpoint:
      scheme: https
    # ...

File (TOML)

[providers.consulCatalog]
  [providers.consulCatalog.endpoint]
    scheme = "https"
    # ...

CLI

--providers.consulcatalog.endpoint.scheme=https
# ...

datacenter

Optional, Default=””

Defines the datacenter to use. If not provided in Traefik, Consul uses the default agent datacenter.

File (YAML)

providers:
  consulCatalog:
    endpoint:
      datacenter: test
    # ...

File (TOML)

[providers.consulCatalog]
  [providers.consulCatalog.endpoint]
    datacenter = "test"
    # ...

CLI

--providers.consulcatalog.endpoint.datacenter=test
# ...

token

Optional, Default=””

Token is used to provide a per-request ACL token which overwrites the agent’s default token.

File (YAML)

providers:
  consulCatalog:
    endpoint:
      token: test
    # ...

File (TOML)

[providers.consulCatalog]
  [providers.consulCatalog.endpoint]
    token = "test"
    # ...

CLI

--providers.consulcatalog.endpoint.token=test
# ...

endpointWaitTime

Optional, Default=””

Limits the duration for which a Watch can block. If not provided, the agent default values will be used.

File (YAML)

providers:
  consulCatalog:
    endpoint:
      endpointWaitTime: 15s
    # ...

File (TOML)

[providers.consulCatalog]
  [providers.consulCatalog.endpoint]
    endpointWaitTime = "15s"
    # ...

CLI

--providers.consulcatalog.endpoint.endpointwaittime=15s
# ...

httpAuth

Optional

Used to authenticate the HTTP client using HTTP Basic Authentication.

username

Optional, Default=””

Username to use for HTTP Basic Authentication.

File (YAML)

providers:
  consulCatalog:
    endpoint:
      httpAuth:
        username: test

File (TOML)

[providers.consulCatalog.endpoint.httpAuth]
  username = "test"

CLI

--providers.consulcatalog.endpoint.httpauth.username=test

password

Optional, Default=””

Password to use for HTTP Basic Authentication.

File (YAML)

providers:
  consulCatalog:
    endpoint:
      httpAuth:
        password: test

File (TOML)

[providers.consulCatalog.endpoint.httpAuth]
  password = "test"

CLI

--providers.consulcatalog.endpoint.httpauth.password=test

tls

Optional

Defines the TLS configuration used for the secure connection to Consul Catalog.

ca

Optional

ca is the path to the certificate authority used for the secure connection to Consul Catalog, it defaults to the system bundle.

File (YAML)

providers:
  consulCatalog:
    endpoint:
      tls:
        ca: path/to/ca.crt

File (TOML)

[providers.consulCatalog.endpoint.tls]
  ca = "path/to/ca.crt"

CLI

--providers.consulcatalog.endpoint.tls.ca=path/to/ca.crt

cert

Optional

cert is the path to the public certificate used for the secure connection to Consul Catalog. When using this option, setting the key option is required.

File (YAML)

providers:
  consulCatalog:
    endpoint:
      tls:
        cert: path/to/foo.cert
        key: path/to/foo.key

File (TOML)

[providers.consulCatalog.endpoint.tls]
  cert = "path/to/foo.cert"
  key = "path/to/foo.key"

CLI

--providers.consulcatalog.endpoint.tls.cert=path/to/foo.cert
--providers.consulcatalog.endpoint.tls.key=path/to/foo.key

key

Optional

key is the path to the private key used for the secure connection to Consul Catalog. When using this option, setting the cert option is required.

File (YAML)

providers:
  consulCatalog:
    endpoint:
      tls:
        cert: path/to/foo.cert
        key: path/to/foo.key

File (TOML)

[providers.consulCatalog.endpoint.tls]
  cert = "path/to/foo.cert"
  key = "path/to/foo.key"

CLI

--providers.consulcatalog.endpoint.tls.cert=path/to/foo.cert
--providers.consulcatalog.endpoint.tls.key=path/to/foo.key

insecureSkipVerify

Optional, Default=false

If insecureSkipVerify is true, the TLS connection to Consul accepts any certificate presented by the server regardless of the hostnames it covers.

File (YAML)

providers:
  consulCatalog:
    endpoint:
      tls:
        insecureSkipVerify: true

File (TOML)

[providers.consulCatalog.endpoint.tls]
  insecureSkipVerify = true

CLI

--providers.consulcatalog.endpoint.tls.insecureskipverify=true

exposedByDefault

Optional, Default=true

Expose Consul Catalog services by default in Traefik. If set to false, services that don’t have a traefik.enable=true tag will be ignored from the resulting routing configuration.

For additional information, refer to Restrict the Scope of Service Discovery.

File (YAML)

providers:
  consulCatalog:
    exposedByDefault: false
    # ...

File (TOML)

[providers.consulCatalog]
  exposedByDefault = false
  # ...

CLI

--providers.consulcatalog.exposedByDefault=false
# ...

defaultRule

Optional, Default=Host(`{{ normalize .Name }}`)

The default host rule for all services.

For a given service, if no routing rule was defined by a tag, it is defined by this defaultRule instead. The defaultRule must be set to a valid Go template, and can include sprig template functions. The service name can be accessed with the Name identifier, and the template has access to all the labels (i.e. tags beginning with the prefix) defined on this service.

The option can be overridden on an instance basis with the traefik.http.routers.{name-of-your-choice}.rule tag.

File (YAML)

providers:
  consulCatalog:
    defaultRule: "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
    # ...

File (TOML)

[providers.consulCatalog]
  defaultRule = "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
  # ...

CLI

--providers.consulcatalog.defaultRule=Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)
# ...

Default rule and Traefik service

The exposure of the Traefik container, combined with the default rule mechanism, can lead to create a router targeting itself in a loop. In this case, to prevent an infinite loop, Traefik adds an internal middleware to refuse the request if it comes from the same router.

connectAware

Optional, Default=false

Enable Consul Connect support. If set to true, Traefik will be enabled to communicate with Connect services.

File (TOML)

[providers.consulCatalog]
  connectAware = true
  # ...

File (YAML)

providers:
  consulCatalog:
    connectAware: true
    # ...

CLI

--providers.consulcatalog.connectAware=true
# ...

connectByDefault

Optional, Default=false

Consider every service as Connect capable by default. If set to true, Traefik will consider every Consul Catalog service to be Connect capable by default. The option can be overridden on an instance basis with the traefik.consulcatalog.connect tag.

File (TOML)

[providers.consulCatalog]
  connectByDefault = true
  # ...

File (YAML)

providers:
  consulCatalog:
    connectByDefault: true
    # ...

CLI

--providers.consulcatalog.connectByDefault=true
# ...

serviceName

Optional, Default=”traefik”

Name of the Traefik service in Consul Catalog.

File (TOML)

[providers.consulCatalog]
  serviceName = "test"
  # ...

File (YAML)

providers:
  consulCatalog:
    serviceName: test
    # ...

CLI

--providers.consulcatalog.serviceName=test
# ...

constraints

Optional, Default=””

The constraints option can be set to an expression that Traefik matches against the service tags to determine whether to create any route for that service. If none of the service tags match the expression, no route for that service is created. If the expression is empty, all detected services are included.

The expression syntax is based on the Tag(`tag`), and TagRegex(`tag`) functions, as well as the usual boolean logic, as shown in examples below.

Constraints Expression Examples

# Includes only services having the tag `a.tag.name=foo`
constraints = "Tag(`a.tag.name=foo`)"

# Excludes services having any tag `a.tag.name=foo`
constraints = "!Tag(`a.tag.name=foo`)"

# With logical AND.
constraints = "Tag(`a.tag.name`) && Tag(`another.tag.name`)"

# With logical OR.
constraints = "Tag(`a.tag.name`) || Tag(`another.tag.name`)"

# With logical AND and OR, with precedence set by parentheses.
constraints = "Tag(`a.tag.name`) && (Tag(`another.tag.name`) || Tag(`yet.another.tag.name`))"

# Includes only services having a tag matching the `a\.tag\.t.+` regular expression.
constraints = "TagRegex(`a\.tag\.t.+`)"

File (YAML)

providers:
  consulCatalog:
    constraints: "Tag(`a.tag.name`)"
    # ...

File (TOML)

[providers.consulCatalog]
  constraints = "Tag(`a.tag.name`)"
  # ...

CLI

--providers.consulcatalog.constraints="Tag(`a.tag.name`)"
# ...

For additional information, refer to Restrict the Scope of Service Discovery.

namespace

Deprecated in favor of the namespaces option.

Optional, Default=””

The namespace option defines the namespace in which the consul catalog services will be discovered.

Warning

The namespace option only works with Consul Enterprise, which provides the Namespaces feature.

Warning

One should only define either the namespaces option or the namespace option.

File (YAML)

providers:
  consulCatalog:
    namespace: "production" 
    # ...

File (TOML)

[providers.consulCatalog]
  namespace = "production"
  # ...

CLI

--providers.consulcatalog.namespace=production
# ...

namespaces

Optional, Default=””

The namespaces option defines the namespaces in which the consul catalog services will be discovered. When using the namespaces option, the discovered configuration object names will be suffixed as shown below:

<resource-name>@consulcatalog-<namespace>

Warning

The namespaces option only works with Consul Enterprise, which provides the Namespaces feature.

Warning

One should only define either the namespaces option or the namespace option.

File (YAML)

providers:
  consulCatalog:
    namespaces: 
      - "ns1"
      - "ns2"
    # ...

File (TOML)

[providers.consulCatalog]
  namespaces = ["ns1", "ns2"]
  # ...

CLI

--providers.consulcatalog.namespaces=ns1,ns2
# ...

watch

Optional, Default=false

When set to true, watches for Consul changes (Consul watches checks).

File (YAML)

providers:
  consulCatalog:
    watch: true
    # ...

File (TOML)

[providers.consulCatalog]
  watch = true
  # ...

CLI

--providers.consulcatalog.watch=true
# ...