10 KiB
title | description |
---|---|
Nomad Service Discovery | Learn how to use Nomad as a provider for configuration discovery in Traefik Proxy. Read the technical documentation. |
Traefik & Nomad Service Discovery
A Story of Tags, Services & Nomads {: .subtitle }
Attach tags to your Nomad services and let Traefik do the rest!
Configuration Examples
??? example "Configuring Nomad & Deploying Services"
Enabling the nomad provider
```yaml tab="File (YAML)"
providers:
nomad: {}
```
```toml tab="File (TOML)"
[providers.nomad]
```
```bash tab="CLI"
--providers.nomad=true
```
Attaching tags to services:
```
...
service {
name = "myService"
tags = [
"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:
nomad:
refreshInterval: 30s
# ...
[providers.nomad]
refreshInterval = "30s"
# ...
--providers.nomad.refreshInterval=30s
# ...
prefix
required, Default="traefik"
The prefix for Nomad service tags defining Traefik labels.
providers:
nomad:
prefix: test
# ...
[providers.nomad]
prefix = "test"
# ...
--providers.nomad.prefix=test
# ...
stale
Optional, Default=false
Use stale consistency for Nomad service API reads.
!!! note ""
This makes reads very fast and scalable at the cost of a higher likelihood of stale values.
For more information, see the Nomad [documentation on consistency](https://www.nomadproject.io/api-docs#consistency-modes).
providers:
nomad:
stale: true
# ...
[providers.nomad]
stale = true
# ...
--providers.nomad.stale=true
# ...
endpoint
Defines the Nomad server endpoint.
address
Defines the address of the Nomad server.
Optional, Default="http://127.0.0.1:4646"
providers:
nomad:
endpoint:
address: http://127.0.0.1:4646
# ...
[providers.nomad]
[providers.nomad.endpoint]
address = "http://127.0.0.1:4646"
# ...
--providers.nomad.endpoint.address=http://127.0.0.1:4646
# ...
datacenter
Optional, Default=""
Defines the datacenter to use. If not provided in Traefik, Nomad uses the agent datacenter.
providers:
nomad:
endpoint:
datacenter: dc1
# ...
[providers.nomad]
[providers.nomad.endpoint]
datacenter = "dc1"
# ...
--providers.nomad.endpoint.datacenter=dc1
# ...
token
Optional, Default=""
Token is used to provide a per-request ACL token, if Nomad ACLs are enabled.
providers:
nomad:
endpoint:
token: test
# ...
[providers.nomad]
[providers.nomad.endpoint]
token = "test"
# ...
--providers.nomad.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:
nomad:
endpoint:
endpointWaitTime: 15s
# ...
[providers.nomad]
[providers.nomad.endpoint]
endpointWaitTime = "15s"
# ...
--providers.nomad.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:
nomad:
endpoint:
httpAuth:
username: admin
[providers.nomad.endpoint.httpAuth]
username = "admin"
--providers.nomad.endpoint.httpauth.username=admin
password
Optional, Default=""
Password to use for HTTP Basic Authentication.
providers:
nomad:
endpoint:
httpAuth:
password: passw0rd
[providers.nomad.endpoint.httpAuth]
password = "passw0rd"
--providers.nomad.endpoint.httpauth.password=passw0rd
tls
Optional
Defines the TLS configuration used for the secure connection to the Nomad API.
ca
Optional
ca
is the path to the certificate authority used for the secure connection to Nomad,
it defaults to the system bundle.
providers:
nomad:
endpoint:
tls:
ca: path/to/ca.crt
[providers.nomad.endpoint.tls]
ca = "path/to/ca.crt"
--providers.nomad.endpoint.tls.ca=path/to/ca.crt
cert
Optional
cert
is the path to the public certificate used for the secure connection to the Nomad API.
When using this option, setting the key
option is required.
providers:
nomad:
endpoint:
tls:
cert: path/to/foo.cert
key: path/to/foo.key
[providers.nomad.endpoint.tls]
cert = "path/to/foo.cert"
key = "path/to/foo.key"
--providers.nomad.endpoint.tls.cert=path/to/foo.cert
--providers.nomad.endpoint.tls.key=path/to/foo.key
key
Optional
key
is the path to the private key used for the secure connection to the Nomad API.
When using this option, setting the cert
option is required.
providers:
nomad:
endpoint:
tls:
cert: path/to/foo.cert
key: path/to/foo.key
[providers.nomad.endpoint.tls]
cert = "path/to/foo.cert"
key = "path/to/foo.key"
--providers.nomad.endpoint.tls.cert=path/to/foo.cert
--providers.nomad.endpoint.tls.key=path/to/foo.key
insecureSkipVerify
Optional, Default=false
If insecureSkipVerify
is true
, the TLS connection to Nomad accepts any certificate presented by the server regardless of the hostnames it covers.
providers:
nomad:
endpoint:
tls:
insecureSkipVerify: true
[providers.nomad.endpoint.tls]
insecureSkipVerify = true
--providers.nomad.endpoint.tls.insecureskipverify=true
exposedByDefault
Optional, Default=true
Expose Nomad services by default in Traefik.
If set to false
, services that do not 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:
nomad:
exposedByDefault: false
# ...
[providers.nomad]
exposedByDefault = false
# ...
--providers.nomad.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:
nomad:
defaultRule: "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
# ...
[providers.nomad]
defaultRule = "Host(`{{ .Name }}.{{ index .Labels \"customLabel\"}}`)"
# ...
--providers.nomad.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.
??? 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:
nomad:
constraints: "Tag(`a.tag.name`)"
# ...
[providers.nomad]
constraints = "Tag(`a.tag.name`)"
# ...
--providers.nomad.constraints="Tag(`a.tag.name`)"
# ...
For additional information, refer to Restrict the Scope of Service Discovery.
namespace
Optional, Default=""
The namespace
option defines the namespace in which the Nomad services will be discovered.
providers:
nomad:
namespace: "production"
# ...
[providers.nomad]
namespace = "production"
# ...
--providers.nomad.namespace=production
# ...