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 (TOML)

[providers.consulCatalog]

File (YAML)

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

File (TOML)

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

File (YAML)

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

CLI

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

Defines the polling interval.

prefix

required, Default="traefik"

File (TOML)

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

File (YAML)

providers:
  consulCatalog:
    prefix: test
    # ...

CLI

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

The prefix for Consul Catalog tags defining traefik labels.

requireConsistent

Optional, Default=false

File (TOML)

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

File (YAML)

providers:
  consulCatalog:
    requireConsistent: true
    # ...

CLI

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

Forces the read to be fully consistent.

stale

Optional, Default=false

File (TOML)

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

File (YAML)

providers:
  consulCatalog:
    stale: true
    # ...

CLI

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

Use stale consistency for catalog reads.

cache

Optional, Default=false

File (TOML)

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

File (YAML)

providers:
  consulCatalog:
    cache: true
    # ...

CLI

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

Use local agent caching for catalog reads.

endpoint

Defines the Consul server endpoint.

address

Optional, Default="127.0.0.1:8500"

File (TOML)

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

File (YAML)

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

CLI

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

Defines the address of the Consul server.

scheme

Optional, Default=""

File (TOML)

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

File (YAML)

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

CLI

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

Defines the URI scheme for the Consul server.

datacenter

Optional, Default=""

File (TOML)

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

File (YAML)

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

CLI

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

Defines the Data center to use. If not provided, the default agent data center is used.

token

Optional, Default=""

File (TOML)

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

File (YAML)

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

CLI

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

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

endpointWaitTime

Optional, Default=""

File (TOML)

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

File (YAML)

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

CLI

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

WaitTime limits how long a Watch will block. If not provided, the agent default values will be used

httpAuth

Optional

Used to authenticate http client with HTTP Basic Authentication.

username

Optional

File (TOML)

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

File (YAML)

providers:
  consulCatalog:
    endpoint:
      httpAuth:
        username: test

CLI

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

Username to use for HTTP Basic Authentication

password

Optional

File (TOML)

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

File (YAML)

providers:
  consulCatalog:
    endpoint:
      httpAuth:
        password: test

CLI

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

Password to use for HTTP Basic Authentication

tls

Optional

Defines TLS options for Consul server endpoint.

ca

Optional

File (TOML)

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

File (YAML)

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

CLI

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

ca is the path to the CA certificate used for Consul communication, defaults to the system bundle if not specified.

caOptional

Optional

File (TOML)

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

File (YAML)

providers:
  consulCatalog:
    endpoint:
      tls:
        caOptional: true

CLI

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

Policy followed for the secured connection with TLS Client Authentication to Consul. Requires tls.ca to be defined.

• true: VerifyClientCertIfGiven
• false: RequireAndVerifyClientCert
• if tls.ca is undefined NoClientCert

cert

Optional

File (TOML)

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

File (YAML)

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

cert is the path to the public certificate for Consul communication. If this is set then you need to also set `key.

key

Optional

File (TOML)

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

File (YAML)

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 is the path to the private key for Consul communication. If this is set then you need to also set cert.

insecureSkipVerify

Optional

File (TOML)

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

File (YAML)

providers:
  consulCatalog:
    endpoint:
      tls:
        insecureSkipVerify: true

CLI

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

If insecureSkipVerify is true, TLS for the connection to Consul server accepts any certificate presented by the server and any host name in that certificate.

exposedByDefault

Optional, Default=true

File (TOML)

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

File (YAML)

providers:
  consulCatalog:
    exposedByDefault: false
    # ...

CLI

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

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.

See also Restrict the Scope of Service Discovery.

defaultRule

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

File (TOML)

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

File (YAML)

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

CLI

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

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. It must be a valid Go template, augmented with the sprig template functions. The service name can be accessed as 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.

constraints

Optional, Default=""

File (TOML)

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

File (YAML)

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

CLI

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

Constraints is an expression that Traefik matches against the service's tags to determine whether to create any route for that service. That is to say, if none of the service's 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.+`)"

See also Restrict the Scope of Service Discovery.