Consul Catalog provider

Reads service registrations from Consul's Catalog (not the KV store) and emits routers and services for them.

Source

pkg/provider/consulcatalog/. Notable files:

• consul_catalog.go — provider definition and main loop.
• config.go — service-registration tags → dynamic configuration.
• client.go — wraps github.com/hashicorp/consul/api.

Configuration

providers:
  consulCatalog:
    endpoint:
      address: consul:8500
    refreshInterval: 30s
    exposedByDefault: false
    prefix: traefik
    namespaces: ['default']
    serviceName: my-service
    constraints: 'Tag(`production`)'
    cache: false
    requireConsistent: false

Consul service registrations are tagged. The provider reads tags shaped like traefik.<router|service>.<name>.<field>=<value>, conceptually mirroring Docker labels.

Behavior

graph LR
    Conf[Static config] --> Init[Init: client setup]
    Init --> Loop[refresh loop]
    Loop -->|list services| API[Consul Catalog API]
    Loop -->|list health| API
    API --> Build[build dynamic.Configuration]
    Build --> Emit[send dynamic.Message]

The polling interval is configurable; a low value makes the provider react quickly to registration changes at the cost of more API traffic. For large catalogs, enable cache: true to use Consul's blocking-query cache.

namespaces lists Consul Enterprise namespaces to consult; the open-source build ignores anything but default.

serviceName filters which service is consumed when only one is desired (useful for multi-tenant setups).

Tags vs labels

Consul tags are unstructured strings, not key-value pairs. The provider uses an = convention to encode key-value semantics:

traefik.enable=true
traefik.http.routers.api.rule=Host(`api.example.com`)
traefik.http.services.api.loadbalancer.server.port=8080

If exposedByDefault is false, traefik.enable=true must be present.

Health filtering

The provider consults Consul's health-check status. By default, only services in the passing state contribute to the router/service. This can be tuned via the watch settings.

Tests

• pkg/provider/consulcatalog/consul_catalog_test.go — table-driven tests using fixture data.
• integration/consul_catalog_test.go — end-to-end against a real Consul instance.

For the KV side of Consul, see KV providers. The two are independent — you can use either or both.