baalajimaestro/traefik
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions
traefik/docs/content/providers/consul-catalog.md
Ludovic Fernandez c5ec12cd56 feat: add consul catalog options
2019-10-31 11:56:05 +01:00

12 KiB
Raw Blame History

Traefik & Consul Catalog

A Story of Labels, Services & Containers {: .subtitle }

Consul Catalog

Attach labels to your services and let Traefik do the rest!

Configuration Examples

??? example "Configuring Consul Catalog & Deploying / Exposing Services"

Enabling the consulcatalog provider

```toml tab="File (TOML)"
[providers.consulCatalog]
```

```yaml tab="File (YAML)"
providers:
  consulCatalog: {}
```

```bash tab="CLI"
--providers.consulcatalog=true
```

Attaching labels to services

```yaml
labels:
  - traefik.http.services.my-service.rule=Host(`mydomain.com`)
```

Routing Configuration

See the dedicated section in routing.

Provider Configuration

refreshInterval

Optional, Default=15s

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

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

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

Defines the polling interval.

prefix

Optional, Default=/latest

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

providers:
  consulCatalog:
    prefix: /test
    # ...

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

Prefix used for accessing the Consul service metadata.

requireConsistent

Optional, Default=false

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

providers:
  consulCatalog:
    requireConsistent: true
    # ...

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

Forces the read to be fully consistent.

stale

Optional, Default=false

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

providers:
  consulCatalog:
    stale: true
    # ...

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

Use stale consistency for catalog reads.

cache

Optional, Default=false

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

providers:
  consulCatalog:
    cache: true
    # ...

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

Use local agent caching for catalog reads.

endpoint

Defines Consul server endpoint.

address

Optional, Default="http://127.0.0.1:8500"

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

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

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

Defines the address of the Consul server.

scheme

Optional, Default=""

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

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

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

Defines the URI scheme for the Consul server.

datacenter

Optional, Default=""

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

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

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

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

token

Optional, Default=""

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

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

--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=""

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

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

--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

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

providers:
  consulCatalog:
    endpoint:
      httpAuth:
        username: test

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

Username to use for HTTP Basic Authentication

password

Optional

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

providers:
  consulCatalog:
    endpoint:
      httpAuth:
        password: test

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

Password to use for HTTP Basic Authentication

tls

Optional

Defines TLS options for Consul server endpoint.

ca

Optional

[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

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

caOptional

Optional

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

providers:
  consulCatalog:
    endpoint:
      tls:
        caOptional: true

--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

[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

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

key

Optional

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

insecureSkipVerify

Optional

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

providers:
  consulCatalog:
    endpoint:
      tls:
        insecureSkipVerify: true

--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

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

providers:
  consulCatalog:
    exposedByDefault: false
    # ...

--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 label will be ignored from the resulting routing configuration.

See also Restrict the Scope of Service Discovery.

defaultRule

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

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

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

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

The default host rule for all services.

For a given container if no routing rule was defined by a label, 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 defined on this container.

This option can be overridden on a container basis with the traefik.http.routers.Router1.rule label.

constraints

Optional, Default=""

[providers.consulCatalog]
  constraints = "Label(`a.label.name`, `foo`)"
  # ...

providers:
  consulCatalog:
    constraints: "Label(`a.label.name`, `foo`)"
    # ...

--providers.consulcatalog.constraints="Label(`a.label.name`, `foo`)"
# ...

Constraints is an expression that Traefik matches against the container's labels to determine whether to create any route for that container. That is to say, if none of the container's labels match the expression, no route for the container is created. If the expression is empty, all detected containers are included.

The expression syntax is based on the Label("key", "value"), and LabelRegex("key", "value") functions, as well as the usual boolean logic, as shown in examples below.

??? example "Constraints Expression Examples"

```toml
# Includes only containers having a label with key `a.label.name` and value `foo`
constraints = "Label(`a.label.name`, `foo`)"
```

```toml
# Excludes containers having any label with key `a.label.name` and value `foo`
constraints = "!Label(`a.label.name`, `value`)"
```

```toml
# With logical AND.
constraints = "Label(`a.label.name`, `valueA`) && Label(`another.label.name`, `valueB`)"
```

```toml
# With logical OR.
constraints = "Label(`a.label.name`, `valueA`) || Label(`another.label.name`, `valueB`)"
```

```toml
# With logical AND and OR, with precedence set by parentheses.
constraints = "Label(`a.label.name`, `valueA`) && (Label(`another.label.name`, `valueB`) || Label(`yet.another.label.name`, `valueC`))"
```

```toml
# Includes only containers having a label with key `a.label.name` and a value matching the `a.+` regular expression.
constraints = "LabelRegex(`a.label.name`, `a.+`)"
```

See also Restrict the Scope of Service Discovery.