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
providers:
consulCatalog: {}
[providers.consulCatalog]
--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.
providers:
consulCatalog:
refreshInterval: 30s
# ...
[providers.consulCatalog]
refreshInterval = "30s"
# ...
--providers.consulcatalog.refreshInterval=30s
# ...
prefix
¶
required, Default="traefik"
The prefix for Consul Catalog tags defining Traefik labels.
providers:
consulCatalog:
prefix: test
# ...
[providers.consulCatalog]
prefix = "test"
# ...
--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.
providers:
consulCatalog:
requireConsistent: true
# ...
[providers.consulCatalog]
requireConsistent = true
# ...
--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.
providers:
consulCatalog:
stale: true
# ...
[providers.consulCatalog]
stale = true
# ...
--providers.consulcatalog.stale=true
# ...
cache
¶
Optional, Default=false
Use local agent caching for catalog reads.
providers:
consulCatalog:
cache: true
# ...
[providers.consulCatalog]
cache = true
# ...
--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"
providers:
consulCatalog:
endpoint:
address: 127.0.0.1:8500
# ...
[providers.consulCatalog]
[providers.consulCatalog.endpoint]
address = "127.0.0.1:8500"
# ...
--providers.consulcatalog.endpoint.address=127.0.0.1:8500
# ...
scheme
¶
Optional, Default=""
Defines the URI scheme for the Consul server.
providers:
consulCatalog:
endpoint:
scheme: https
# ...
[providers.consulCatalog]
[providers.consulCatalog.endpoint]
scheme = "https"
# ...
--providers.consulcatalog.endpoint.scheme=https
# ...
datacenter
¶
Optional, Default=""
Defines the datacenter to use. If not provided in Traefik, Consul uses the default agent datacenter.
providers:
consulCatalog:
endpoint:
datacenter: test
# ...
[providers.consulCatalog]
[providers.consulCatalog.endpoint]
datacenter = "test"
# ...
--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.
providers:
consulCatalog:
endpoint:
token: test
# ...
[providers.consulCatalog]
[providers.consulCatalog.endpoint]
token = "test"
# ...
--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.
providers:
consulCatalog:
endpoint:
endpointWaitTime: 15s
# ...
[providers.consulCatalog]
[providers.consulCatalog.endpoint]
endpointWaitTime = "15s"
# ...
--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.
providers:
consulCatalog:
endpoint:
httpAuth:
username: test
[providers.consulCatalog.endpoint.httpAuth]
username = "test"
--providers.consulcatalog.endpoint.httpauth.username=test
password
¶
Optional, Default=""
Password to use for HTTP Basic Authentication.
providers:
consulCatalog:
endpoint:
httpAuth:
password: test
[providers.consulCatalog.endpoint.httpAuth]
password = "test"
--providers.consulcatalog.endpoint.httpauth.password=test
tls
¶
Optional
Defines TLS options for Consul server endpoint.
ca
¶
Optional
ca
is the path to the CA certificate used for Consul communication, defaults to the system bundle if not specified.
providers:
consulCatalog:
endpoint:
tls:
ca: path/to/ca.crt
[providers.consulCatalog.endpoint.tls]
ca = "path/to/ca.crt"
--providers.consulcatalog.endpoint.tls.ca=path/to/ca.crt
caOptional
¶
Optional
The value of tls.caOptional
defines which policy should be used for the secure connection with TLS Client Authentication to Consul.
If tls.ca
is undefined, this option will be ignored, and no client certificate will be requested during the handshake. Any provided certificate will thus never be verified.
When this option is set to true
, a client certificate is requested during the handshake but is not required. If a certificate is sent, it is required to be valid.
When this option is set to false
, a client certificate is requested during the handshake, and at least one valid certificate should be sent by the client.
providers:
consulCatalog:
endpoint:
tls:
caOptional: true
[providers.consulCatalog.endpoint.tls]
caOptional = true
--providers.consulcatalog.endpoint.tls.caoptional=true
cert
¶
Optional
cert
is the path to the public certificate to use for Consul communication.
When using this option, setting the key
option is required.
providers:
consulCatalog:
endpoint:
tls:
cert: path/to/foo.cert
key: path/to/foo.key
[providers.consulCatalog.endpoint.tls]
cert = "path/to/foo.cert"
key = "path/to/foo.key"
--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 for Consul communication.
When using this option, setting the cert
option is required.
providers:
consulCatalog:
endpoint:
tls:
cert: path/to/foo.cert
key: path/to/foo.key
[providers.consulCatalog.endpoint.tls]
cert = "path/to/foo.cert"
key = "path/to/foo.key"
--providers.consulcatalog.endpoint.tls.cert=path/to/foo.cert
--providers.consulcatalog.endpoint.tls.key=path/to/foo.key
insecureSkipVerify
¶
Optional
If insecureSkipVerify
is true
, the TLS connection to Consul accepts any certificate presented by the server regardless of the hostnames it covers.
providers:
consulCatalog:
endpoint:
tls:
insecureSkipVerify: true
[providers.consulCatalog.endpoint.tls]
insecureSkipVerify = true
--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.
providers:
consulCatalog:
exposedByDefault: false
# ...
[providers.consulCatalog]
exposedByDefault = false
# ...
--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.
providers:
consulCatalog:
defaultRule: "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
# ...
[providers.consulCatalog]
defaultRule = "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
# ...
--providers.consulcatalog.defaultRule="Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
# ...
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.+`)"
providers:
consulCatalog:
constraints: "Tag(`a.tag.name`)"
# ...
[providers.consulCatalog]
constraints = "Tag(`a.tag.name`)"
# ...
--providers.consulcatalog.constraints="Tag(`a.tag.name`)"
# ...
For additional information, refer to Restrict the Scope of Service Discovery.