traefik/docs/content/providers/consul-catalog.md

753 lines
15 KiB
Markdown
Raw Normal View History

---
title: "Consul Catalog Configuration Discovery"
description: "Learn how to use Consul Catalog as a provider for configuration discovery in Traefik Proxy. Read the technical documentation."
---
2019-10-15 15:34:08 +00:00
# Traefik & Consul Catalog
2019-11-29 16:16:05 +00:00
A Story of Tags, Services & Instances
2019-10-15 15:34:08 +00:00
{: .subtitle }
![Consul Catalog](../assets/img/providers/consul.png)
2019-11-29 16:16:05 +00:00
Attach tags to your services and let Traefik do the rest!
2019-10-15 15:34:08 +00:00
## Configuration Examples
??? example "Configuring Consul Catalog & Deploying / Exposing Services"
2019-11-29 16:16:05 +00:00
Enabling the consul catalog provider
2019-10-15 15:34:08 +00:00
```yaml tab="File (YAML)"
providers:
2019-10-29 11:32:05 +00:00
consulCatalog: {}
2019-10-15 15:34:08 +00:00
```
2021-02-11 18:04:03 +00:00
```toml tab="File (TOML)"
[providers.consulCatalog]
```
2019-10-15 15:34:08 +00:00
```bash tab="CLI"
--providers.consulcatalog=true
```
2019-11-29 16:16:05 +00:00
Attaching tags to services
2019-10-15 15:34:08 +00:00
```yaml
2020-09-23 09:56:03 +00:00
- traefik.http.routers.my-router.rule=Host(`example.com`)
2019-10-15 15:34:08 +00:00
```
## Routing Configuration
See the dedicated section in [routing](../routing/providers/consul-catalog.md).
## Provider Configuration
2019-10-31 10:56:05 +00:00
### `refreshInterval`
2019-10-15 15:34:08 +00:00
2019-10-31 10:56:05 +00:00
_Optional, Default=15s_
2019-10-15 15:34:08 +00:00
2021-02-11 18:04:03 +00:00
Defines the polling interval.
2019-10-15 15:34:08 +00:00
```yaml tab="File (YAML)"
providers:
2019-10-29 11:32:05 +00:00
consulCatalog:
2019-10-31 10:56:05 +00:00
refreshInterval: 30s
2019-10-15 15:34:08 +00:00
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
refreshInterval = "30s"
# ...
```
2019-10-15 15:34:08 +00:00
```bash tab="CLI"
2019-10-31 10:56:05 +00:00
--providers.consulcatalog.refreshInterval=30s
2019-10-15 15:34:08 +00:00
# ...
```
2019-10-31 10:56:05 +00:00
### `prefix`
2019-10-15 15:34:08 +00:00
2019-11-29 16:16:05 +00:00
_required, Default="traefik"_
2019-10-15 15:34:08 +00:00
2021-02-11 18:04:03 +00:00
The prefix for Consul Catalog tags defining Traefik labels.
2019-10-15 15:34:08 +00:00
```yaml tab="File (YAML)"
providers:
2019-10-29 11:32:05 +00:00
consulCatalog:
2019-11-29 16:16:05 +00:00
prefix: test
2019-10-15 15:34:08 +00:00
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
prefix = "test"
# ...
```
2019-10-15 15:34:08 +00:00
```bash tab="CLI"
2019-11-29 16:16:05 +00:00
--providers.consulcatalog.prefix=test
2019-10-15 15:34:08 +00:00
# ...
```
2019-10-31 10:56:05 +00:00
### `requireConsistent`
2019-10-15 15:34:08 +00:00
2019-10-31 10:56:05 +00:00
_Optional, Default=false_
2019-10-15 15:34:08 +00:00
2021-02-11 18:04:03 +00:00
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).
2019-10-15 15:34:08 +00:00
```yaml tab="File (YAML)"
providers:
2019-10-29 11:32:05 +00:00
consulCatalog:
2019-10-31 10:56:05 +00:00
requireConsistent: true
2019-10-15 15:34:08 +00:00
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
requireConsistent = true
# ...
```
2019-10-15 15:34:08 +00:00
```bash tab="CLI"
2019-10-31 10:56:05 +00:00
--providers.consulcatalog.requireConsistent=true
2019-10-15 15:34:08 +00:00
# ...
```
2019-10-31 10:56:05 +00:00
### `stale`
2019-10-15 15:34:08 +00:00
2019-10-31 10:56:05 +00:00
_Optional, Default=false_
2019-10-15 15:34:08 +00:00
2021-02-11 18:04:03 +00:00
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).
2019-10-15 15:34:08 +00:00
```yaml tab="File (YAML)"
providers:
2019-10-29 11:32:05 +00:00
consulCatalog:
2019-10-31 10:56:05 +00:00
stale: true
2019-10-15 15:34:08 +00:00
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
stale = true
# ...
```
2019-10-15 15:34:08 +00:00
```bash tab="CLI"
2019-10-31 10:56:05 +00:00
--providers.consulcatalog.stale=true
2019-10-15 15:34:08 +00:00
# ...
```
2019-10-31 10:56:05 +00:00
### `cache`
2019-10-15 15:34:08 +00:00
2019-10-31 10:56:05 +00:00
_Optional, Default=false_
2019-10-15 15:34:08 +00:00
2021-02-11 18:04:03 +00:00
Use local agent caching for catalog reads.
2019-10-15 15:34:08 +00:00
```yaml tab="File (YAML)"
providers:
2019-10-29 11:32:05 +00:00
consulCatalog:
2019-10-31 10:56:05 +00:00
cache: true
2019-10-15 15:34:08 +00:00
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
cache = true
# ...
```
2019-10-15 15:34:08 +00:00
```bash tab="CLI"
2019-10-31 10:56:05 +00:00
--providers.consulcatalog.cache=true
2019-10-15 15:34:08 +00:00
# ...
```
2019-10-29 11:32:05 +00:00
### `endpoint`
2019-11-29 16:16:05 +00:00
Defines the Consul server endpoint.
2019-10-29 11:32:05 +00:00
#### `address`
2021-02-11 18:04:03 +00:00
Defines the address of the Consul server.
_Optional, Default="127.0.0.1:8500"_
2019-10-29 11:32:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
endpoint:
address: 127.0.0.1:8500
2019-10-29 11:32:05 +00:00
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
[providers.consulCatalog.endpoint]
address = "127.0.0.1:8500"
# ...
```
2019-10-29 11:32:05 +00:00
```bash tab="CLI"
--providers.consulcatalog.endpoint.address=127.0.0.1:8500
2019-10-29 11:32:05 +00:00
# ...
```
#### `scheme`
_Optional, Default=""_
2021-02-11 18:04:03 +00:00
Defines the URI scheme for the Consul server.
2019-10-29 11:32:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
endpoint:
scheme: https
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
[providers.consulCatalog.endpoint]
scheme = "https"
# ...
```
2019-10-29 11:32:05 +00:00
```bash tab="CLI"
--providers.consulcatalog.endpoint.scheme=https
# ...
```
#### `datacenter`
_Optional, Default=""_
2021-02-11 18:04:03 +00:00
Defines the datacenter to use.
If not provided in Traefik, Consul uses the default agent datacenter.
2019-10-29 11:32:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
endpoint:
datacenter: test
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
[providers.consulCatalog.endpoint]
datacenter = "test"
# ...
```
2019-10-29 11:32:05 +00:00
```bash tab="CLI"
--providers.consulcatalog.endpoint.datacenter=test
# ...
```
#### `token`
_Optional, Default=""_
2021-02-11 18:04:03 +00:00
Token is used to provide a per-request ACL token which overwrites the agent's default token.
2019-10-29 11:32:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
endpoint:
token: test
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
[providers.consulCatalog.endpoint]
token = "test"
# ...
```
2019-10-29 11:32:05 +00:00
```bash tab="CLI"
--providers.consulcatalog.endpoint.token=test
# ...
```
#### `endpointWaitTime`
_Optional, Default=""_
2021-02-11 18:04:03 +00:00
Limits the duration for which a Watch can block.
If not provided, the agent default values will be used.
2019-10-29 11:32:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
endpoint:
endpointWaitTime: 15s
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
[providers.consulCatalog.endpoint]
endpointWaitTime = "15s"
# ...
```
2019-10-29 11:32:05 +00:00
```bash tab="CLI"
--providers.consulcatalog.endpoint.endpointwaittime=15s
# ...
```
#### `httpAuth`
_Optional_
2021-02-11 18:04:03 +00:00
Used to authenticate the HTTP client using HTTP Basic Authentication.
2019-10-29 11:32:05 +00:00
##### `username`
2021-02-11 18:04:03 +00:00
_Optional, Default=""_
Username to use for HTTP Basic Authentication.
2019-10-29 11:32:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
endpoint:
httpAuth:
username: test
```
```toml tab="File (TOML)"
[providers.consulCatalog.endpoint.httpAuth]
username = "test"
```
2019-10-29 11:32:05 +00:00
```bash tab="CLI"
--providers.consulcatalog.endpoint.httpauth.username=test
```
##### `password`
2021-02-11 18:04:03 +00:00
_Optional, Default=""_
Password to use for HTTP Basic Authentication.
2019-10-29 11:32:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
endpoint:
httpAuth:
password: test
```
```toml tab="File (TOML)"
[providers.consulCatalog.endpoint.httpAuth]
password = "test"
```
2019-10-29 11:32:05 +00:00
```bash tab="CLI"
--providers.consulcatalog.endpoint.httpauth.password=test
```
#### `tls`
_Optional_
Defines the TLS configuration used for the secure connection to Consul Catalog.
2019-10-29 11:32:05 +00:00
##### `ca`
_Optional_
`ca` is the path to the certificate authority used for the secure connection to Consul Catalog,
it defaults to the system bundle.
2021-02-11 18:04:03 +00:00
2019-10-29 11:32:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
endpoint:
tls:
ca: path/to/ca.crt
```
```toml tab="File (TOML)"
[providers.consulCatalog.endpoint.tls]
ca = "path/to/ca.crt"
```
2019-10-29 11:32:05 +00:00
```bash tab="CLI"
--providers.consulcatalog.endpoint.tls.ca=path/to/ca.crt
```
##### `caOptional`
_Optional_
The value of `caOptional` defines which policy should be used for the secure connection with TLS Client Authentication to Consul Catalog.
2021-02-11 18:04:03 +00:00
!!! warning ""
If `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.
2021-02-11 18:04:03 +00:00
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.
2019-10-29 11:32:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
endpoint:
tls:
caOptional: true
```
```toml tab="File (TOML)"
[providers.consulCatalog.endpoint.tls]
caOptional = true
```
2019-10-29 11:32:05 +00:00
```bash tab="CLI"
--providers.consulcatalog.endpoint.tls.caoptional=true
```
##### `cert`
_Optional_
`cert` is the path to the public certificate used for the secure connection to Consul Catalog.
2021-02-11 18:04:03 +00:00
When using this option, setting the `key` option is required.
2019-10-29 11:32:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
endpoint:
tls:
cert: path/to/foo.cert
key: path/to/foo.key
```
```toml tab="File (TOML)"
[providers.consulCatalog.endpoint.tls]
cert = "path/to/foo.cert"
key = "path/to/foo.key"
```
2019-10-29 11:32:05 +00:00
```bash tab="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.
2021-02-11 18:04:03 +00:00
When using this option, setting the `cert` option is required.
2019-10-29 11:32:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
endpoint:
tls:
cert: path/to/foo.cert
key: path/to/foo.key
```
```toml tab="File (TOML)"
[providers.consulCatalog.endpoint.tls]
cert = "path/to/foo.cert"
key = "path/to/foo.key"
```
2019-10-29 11:32:05 +00:00
```bash tab="CLI"
--providers.consulcatalog.endpoint.tls.cert=path/to/foo.cert
--providers.consulcatalog.endpoint.tls.key=path/to/foo.key
```
##### `insecureSkipVerify`
_Optional, Default=false_
2019-10-29 11:32:05 +00:00
2021-02-11 18:04:03 +00:00
If `insecureSkipVerify` is `true`, the TLS connection to Consul accepts any certificate presented by the server regardless of the hostnames it covers.
2019-10-29 11:32:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
endpoint:
tls:
insecureSkipVerify: true
```
```toml tab="File (TOML)"
[providers.consulCatalog.endpoint.tls]
insecureSkipVerify = true
```
2019-10-29 11:32:05 +00:00
```bash tab="CLI"
--providers.consulcatalog.endpoint.tls.insecureskipverify=true
```
2019-10-31 10:56:05 +00:00
### `exposedByDefault`
_Optional, Default=true_
2021-02-11 18:04:03 +00:00
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](./overview.md#restrict-the-scope-of-service-discovery).
2019-10-31 10:56:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
exposedByDefault: false
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
exposedByDefault = false
# ...
```
2019-10-31 10:56:05 +00:00
```bash tab="CLI"
--providers.consulcatalog.exposedByDefault=false
# ...
```
### `defaultRule`
_Optional, Default=```Host(`{{ normalize .Name }}`)```_
2021-02-11 18:04:03 +00:00
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.
2021-09-10 09:42:07 +00:00
The `defaultRule` must be set to a valid [Go template](https://pkg.go.dev/text/template/),
2021-08-31 16:54:06 +00:00
and can include [sprig template functions](https://masterminds.github.io/sprig/).
2021-02-11 18:04:03 +00:00
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.
2019-10-31 10:56:05 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
defaultRule: "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
defaultRule = "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
# ...
```
2019-10-31 10:56:05 +00:00
```bash tab="CLI"
--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.
```toml tab="File (TOML)"
[providers.consulCatalog]
connectAware = true
# ...
```
```yaml tab="File (YAML)"
providers:
consulCatalog:
connectAware: true
# ...
```
```bash tab="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.
```toml tab="File (TOML)"
[providers.consulCatalog]
connectByDefault = true
# ...
```
```yaml tab="File (YAML)"
providers:
consulCatalog:
connectByDefault: true
# ...
```
```bash tab="CLI"
--providers.consulcatalog.connectByDefault=true
# ...
```
### `serviceName`
_Optional, Default="traefik"_
Name of the Traefik service in Consul Catalog.
```toml tab="File (TOML)"
[providers.consulCatalog]
serviceName = "test"
# ...
```
```yaml tab="File (YAML)"
providers:
consulCatalog:
serviceName: test
# ...
```
```bash tab="CLI"
--providers.consulcatalog.serviceName=test
# ...
```
2019-10-31 10:56:05 +00:00
### `constraints`
_Optional, Default=""_
2021-02-11 18:04:03 +00:00
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.
2019-10-31 10:56:05 +00:00
2020-02-13 09:26:04 +00:00
The expression syntax is based on the ```Tag(`tag`)```, and ```TagRegex(`tag`)``` functions,
2019-11-29 16:16:05 +00:00
as well as the usual boolean logic, as shown in examples below.
2019-10-31 10:56:05 +00:00
??? example "Constraints Expression Examples"
```toml
2019-11-29 16:16:05 +00:00
# Includes only services having the tag `a.tag.name=foo`
constraints = "Tag(`a.tag.name=foo`)"
2019-10-31 10:56:05 +00:00
```
2021-02-11 18:04:03 +00:00
2019-10-31 10:56:05 +00:00
```toml
2019-11-29 16:16:05 +00:00
# Excludes services having any tag `a.tag.name=foo`
constraints = "!Tag(`a.tag.name=foo`)"
2019-10-31 10:56:05 +00:00
```
2021-02-11 18:04:03 +00:00
2019-10-31 10:56:05 +00:00
```toml
# With logical AND.
2019-11-29 16:16:05 +00:00
constraints = "Tag(`a.tag.name`) && Tag(`another.tag.name`)"
2019-10-31 10:56:05 +00:00
```
2021-02-11 18:04:03 +00:00
2019-10-31 10:56:05 +00:00
```toml
# With logical OR.
2019-11-29 16:16:05 +00:00
constraints = "Tag(`a.tag.name`) || Tag(`another.tag.name`)"
2019-10-31 10:56:05 +00:00
```
2021-02-11 18:04:03 +00:00
2019-10-31 10:56:05 +00:00
```toml
# With logical AND and OR, with precedence set by parentheses.
2019-11-29 16:16:05 +00:00
constraints = "Tag(`a.tag.name`) && (Tag(`another.tag.name`) || Tag(`yet.another.tag.name`))"
2019-10-31 10:56:05 +00:00
```
2021-02-11 18:04:03 +00:00
2019-10-31 10:56:05 +00:00
```toml
2019-11-29 16:16:05 +00:00
# Includes only services having a tag matching the `a\.tag\.t.+` regular expression.
constraints = "TagRegex(`a\.tag\.t.+`)"
2019-10-31 10:56:05 +00:00
```
2021-02-11 18:04:03 +00:00
```yaml tab="File (YAML)"
providers:
consulCatalog:
constraints: "Tag(`a.tag.name`)"
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
constraints = "Tag(`a.tag.name`)"
# ...
```
2021-02-11 18:04:03 +00:00
```bash tab="CLI"
--providers.consulcatalog.constraints="Tag(`a.tag.name`)"
# ...
```
For additional information, refer to [Restrict the Scope of Service Discovery](./overview.md#restrict-the-scope-of-service-discovery).
### `namespace`
_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](https://www.consul.io/docs/enterprise),
which provides the [Namespaces](https://www.consul.io/docs/enterprise/namespaces) feature.
```yaml tab="File (YAML)"
providers:
consulCatalog:
namespace: "production"
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
namespace = "production"
# ...
```
```bash tab="CLI"
--providers.consulcatalog.namespace=production
# ...
```
### `watch`
_Optional, Default=false_
When set to `true`, watches for Consul changes ([Consul watches checks](https://www.consul.io/docs/dynamic-app-config/watches#checks)).
```yaml tab="File (YAML)"
providers:
consulCatalog:
watch: true
# ...
```
```toml tab="File (TOML)"
[providers.consulCatalog]
watch = true
# ...
```
```bash tab="CLI"
--providers.consulcatalog.watch=true
# ...
```