Co-authored-by: Florian Apolloner <apollo13@users.noreply.github.com>
14 KiB
Traefik & Consul Catalog
A Story of Tags, Services & Instances {: .subtitle }
Attach tags to your services and let Traefik do the rest!
Configuration Examples
??? example "Configuring Consul Catalog & Deploying / Exposing Services"
Enabling the consul catalog provider
```yaml tab="File (YAML)"
providers:
consulCatalog: {}
```
```toml tab="File (TOML)"
[providers.consulCatalog]
```
```bash tab="CLI"
--providers.consulcatalog=true
```
Attaching tags to services
```yaml
- 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.
!!! note ""
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](https://www.consul.io/api-docs/features/consistency).
providers:
consulCatalog:
requireConsistent: true
# ...
[providers.consulCatalog]
requireConsistent = true
# ...
--providers.consulcatalog.requireConsistent=true
# ...
stale
Optional, Default=false
Use stale consistency for catalog reads.
!!! note ""
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](https://www.consul.io/api-docs/features/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.
!!! warning ""
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\"}}`)"
# ...
connectAware
Optional, Default=false
Enable Consul Connect support.
If set to true
, Traefik will be enabled to communicate with Connect services.
[providers.consulCatalog]
connectAware = true
# ...
providers:
consulCatalog:
connectAware: true
# ...
--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.
[providers.consulCatalog]
connectByDefault = true
# ...
providers:
consulCatalog:
connectByDefault: true
# ...
--providers.consulcatalog.connectByDefault=true
# ...
serviceName
Optional, Default="traefik"
Name of the Traefik service in Consul Catalog.
[providers.consulCatalog]
serviceName = "test"
# ...
providers:
consulCatalog:
serviceName: test
# ...
--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.
??? example "Constraints Expression Examples"
```toml
# Includes only services having the tag `a.tag.name=foo`
constraints = "Tag(`a.tag.name=foo`)"
```
```toml
# Excludes services having any tag `a.tag.name=foo`
constraints = "!Tag(`a.tag.name=foo`)"
```
```toml
# With logical AND.
constraints = "Tag(`a.tag.name`) && Tag(`another.tag.name`)"
```
```toml
# With logical OR.
constraints = "Tag(`a.tag.name`) || Tag(`another.tag.name`)"
```
```toml
# With logical AND and OR, with precedence set by parentheses.
constraints = "Tag(`a.tag.name`) && (Tag(`another.tag.name`) || Tag(`yet.another.tag.name`))"
```
```toml
# 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.