Consul Catalog Provider

A Story of Tags, Services & Instances Attach tags to your Consul services and let Traefik automatically discover and route traffic. The Consul Catalog provider watches service registrations in HashiCorp Consul and dynamically updates routing configuration.

Quick Start

Enable Consul Catalog Provider

providers:
  consulCatalog:
    endpoint:
      address: "127.0.0.1:8500"
    exposedByDefault: true
    prefix: "traefik"

[providers.consulCatalog]
  [providers.consulCatalog.endpoint]
    address = "127.0.0.1:8500"
  exposedByDefault = true
  prefix = "traefik"

--providers.consulcatalog=true
--providers.consulcatalog.endpoint.address=127.0.0.1:8500

{
  "ID": "web-1",
  "Name": "web",
  "Tags": [
    "traefik.enable=true",
    "traefik.http.routers.web.rule=Host(`example.com`)",
    "traefik.http.services.web.loadbalancer.server.port=8080"
  ],
  "Address": "192.168.1.10",
  "Port": 8080
}

Access Your Service

Traefik automatically detects the service and creates routes!

How It Works

The Consul Catalog provider:

Polls Consul at regular intervals (or uses watch mode)
Discovers services with tags matching the configured prefix
Extracts routing configuration from service tags
Creates routes dynamically
Updates on changes when services are added/removed

Service Registration Examples

Basic HTTP Service

{
  "ID": "api-1",
  "Name": "api",
  "Tags": [
    "traefik.enable=true",
    "traefik.http.routers.api.rule=Host(`api.example.com`)",
    "traefik.http.routers.api.entrypoints=websecure",
    "traefik.http.routers.api.tls=true"
  ],
  "Address": "192.168.1.20",
  "Port": 8080,
  "Check": {
    "HTTP": "http://192.168.1.20:8080/health",
    "Interval": "10s"
  }
}

consul services register -name=api \
  -address=192.168.1.20 \
  -port=8080 \
  -tag="traefik.enable=true" \
  -tag="traefik.http.routers.api.rule=Host(\`api.example.com\`)" \
  -tag="traefik.http.routers.api.entrypoints=websecure"

Service with Middleware

{
  "Name": "secure-app",
  "Tags": [
    "traefik.enable=true",
    "traefik.http.routers.app.rule=Host(`app.example.com`)",
    "traefik.http.routers.app.middlewares=auth,compress",
    "traefik.http.middlewares.auth.basicauth.users=admin:$apr1$...",
    "traefik.http.middlewares.compress.compress=true"
  ],
  "Address": "192.168.1.30",
  "Port": 3000
}

Multiple Routers per Service

{
  "Name": "multi-domain",
  "Tags": [
    "traefik.enable=true",
    
    "traefik.http.routers.www.rule=Host(`example.com`) || Host(`www.example.com`)",
    "traefik.http.routers.www.entrypoints=websecure",
    
    "traefik.http.routers.api.rule=Host(`api.example.com`)",
    "traefik.http.routers.api.entrypoints=websecure",
    "traefik.http.routers.api.middlewares=api-auth"
  ],
  "Address": "192.168.1.40",
  "Port": 8080
}

Provider Configuration

endpoint

Consul server connection settings.

address

Default: 127.0.0.1:8500

providers:
  consulCatalog:
    endpoint:
      address: "consul.example.com:8500"

scheme

Optional, Default: "" URI scheme (http or https):

providers:
  consulCatalog:
    endpoint:
      address: "consul.example.com:8500"
      scheme: "https"

datacenter

Optional, Default: Agent’s datacenter

providers:
  consulCatalog:
    endpoint:
      datacenter: "dc1"

token

Optional, Default: "" Consul ACL token:

providers:
  consulCatalog:
    endpoint:
      token: "your-acl-token"

Don’t commit tokens to version control. Use environment variables or secret management.

httpAuth

HTTP Basic Authentication:

providers:
  consulCatalog:
    endpoint:
      httpAuth:
        username: "admin"
        password: "secret"

tls

TLS configuration for secure connection:

providers:
  consulCatalog:
    endpoint:
      scheme: "https"
      tls:
        ca: "/path/to/ca.crt"
        cert: "/path/to/client.crt"
        key: "/path/to/client.key"
        insecureSkipVerify: false

prefix

Default: traefik Tag prefix for Traefik configuration:

providers:
  consulCatalog:
    prefix: "lb"  # Use tags like: lb.http.routers.app.rule=...

refreshInterval

Default: 15s Polling interval:

providers:
  consulCatalog:
    refreshInterval: "30s"

Ignored when watch: true is enabled.

watch

Optional, Default: false Use Consul watches for real-time updates:

providers:
  consulCatalog:
    watch: true

exposedByDefault

Default: true Expose all services by default:

providers:
  consulCatalog:
    exposedByDefault: false  # Require traefik.enable=true tag

defaultRule

Default: Host(`{{ normalize .Name }}`) Default routing rule template:

providers:
  consulCatalog:
    defaultRule: "Host(`{{ .Name }}.example.com`)"

constraints

Optional, Default: "" Filter services by tags:

providers:
  consulCatalog:
    constraints: "Tag(`production`)"

providers:
  consulCatalog:
    constraints: "Tag(`production`) && Tag(`web`)"

providers:
  consulCatalog:
    constraints: "TagRegex(`env-.*`)"

Consistency Mode

Control Consul read consistency:

requireConsistent

Default: false Force fully consistent reads:

providers:
  consulCatalog:
    requireConsistent: true

stale

Default: false Allow stale reads (faster, scalable):

providers:
  consulCatalog:
    stale: true

cache

Default: false Use local agent caching:

providers:
  consulCatalog:
    cache: true

Consul Connect

connectAware

Default: false Enable Consul Connect support:

providers:
  consulCatalog:
    connectAware: true

connectByDefault

Default: false Treat all services as Connect-capable:

providers:
  consulCatalog:
    connectByDefault: true

namespaces (Enterprise)

Optional, Default: "" Watch specific Consul Enterprise namespaces:

providers:
  consulCatalog:
    namespaces:
      - "production"
      - "staging"

Requires Consul Enterprise with namespace support.

strictChecks

Default: ["passing", "warning"] Health check statuses allowed to receive traffic:

providers:
  consulCatalog:
    strictChecks:
      - "passing"  # Only healthy services

Complete Example

# traefik.yml
entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

providers:
  consulCatalog:
    endpoint:
      address: "consul.internal:8500"
      scheme: "https"
      datacenter: "dc1"
      token: "${CONSUL_TOKEN}"
      tls:
        ca: "/certs/consul-ca.crt"
    
    prefix: "traefik"
    watch: true
    exposedByDefault: false
    
    constraints: "Tag(`production`)"
    
    defaultRule: "Host(`{{ .Name }}.prod.example.com`)"
    
    strictChecks:
      - "passing"

{
  "ID": "web-prod-1",
  "Name": "web",
  "Tags": [
    "production",
    "traefik.enable=true",
    "traefik.http.routers.web.rule=Host(`www.example.com`)",
    "traefik.http.routers.web.entrypoints=websecure",
    "traefik.http.routers.web.tls.certresolver=letsencrypt",
    "traefik.http.routers.web.middlewares=compress,security",
    "traefik.http.middlewares.compress.compress=true",
    "traefik.http.middlewares.security.headers.sslredirect=true",
    "traefik.http.services.web.loadbalancer.server.port=8080",
    "traefik.http.services.web.loadbalancer.healthcheck.path=/health",
    "traefik.http.services.web.loadbalancer.healthcheck.interval=10s"
  ],
  "Address": "10.0.1.10",
  "Port": 8080,
  "Meta": {
    "version": "v1.2.3",
    "region": "us-east"
  },
  "Check": {
    "HTTP": "http://10.0.1.10:8080/health",
    "Interval": "10s",
    "Timeout": "2s"
  }
}

Advanced Patterns

Canary Deployments

// Stable version (90% traffic)
{
  "Name": "api",
  "Tags": [
    "traefik.enable=true",
    "traefik.http.services.api.loadbalancer.server.port=8080",
    "traefik.http.services.api.loadbalancer.weight=90"
  ],
  "Address": "10.0.1.20",
  "Meta": {"version": "v1.0"}
}

// Canary version (10% traffic)
{
  "Name": "api",
  "Tags": [
    "traefik.enable=true",
    "traefik.http.services.api-canary.loadbalancer.server.port=8080",
    "traefik.http.services.api-canary.loadbalancer.weight=10"
  ],
  "Address": "10.0.1.21",
  "Meta": {"version": "v2.0-beta"}
}

Multi-Datacenter Setup

providers:
  consulCatalog:
    endpoint:
      address: "consul.example.com:8500"
      datacenter: "dc1"
    constraints: "Tag(`dc1`)"

{
  "Name": "api",
  "Tags": ["dc1", "traefik.enable=true"],
  "Address": "10.1.1.10"
}

Service Mesh with Consul Connect

providers:
  consulCatalog:
    connectAware: true
    endpoint:
      address: "localhost:8500"

{
  "Name": "backend",
  "Port": 8080,
  "Connect": {
    "SidecarService": {}
  },
  "Tags": [
    "traefik.enable=true",
    "traefik.consulcatalog.connect=true"
  ]
}

Tag Syntax

All Traefik labels work as Consul tags, replacing . with the prefix:

Docker Labels
Consul Tags

traefik.http.routers.app.rule=Host(`example.com`)
traefik.http.routers.app.middlewares=auth

[
  "traefik.http.routers.app.rule=Host(`example.com`)",
  "traefik.http.routers.app.middlewares=auth"
]

Troubleshooting

Services Not Discovered

Check Consul Connection

curl http://127.0.0.1:8500/v1/catalog/services

Verify Service Tags

consul catalog services -tags

Ensure tags start with configured prefix.

Check exposedByDefault

If false, ensure service has traefik.enable=true tag.

Review Constraints

Verify service tags match configured constraints.

Health Checks Failing

# Only use healthy services
providers:
  consulCatalog:
    strictChecks:
      - "passing"

ACL Errors

Ensure token has proper permissions:

service "" {
  policy = "read"
}

node "" {
  policy = "read"
}

Best Practices

Use Health Checks

Always configure Consul health checks for services.

Enable Watch Mode

Use watch: true for real-time updates instead of polling.

Set Proper Consistency

Use stale: true for better performance in large deployments.

Tag Consistently

Develop a tagging strategy (environment, version, team, etc.).

Secure Communication

Use TLS and ACL tokens for Consul connections.

Next Steps

Routing Overview

Learn about routing configuration

Consul Documentation

Official HashiCorp Consul documentation

​Consul Catalog Provider

​Quick Start

​How It Works

​Service Registration Examples

​Basic HTTP Service

​Service with Middleware

​Multiple Routers per Service

​Provider Configuration

​endpoint

​address

​scheme

​datacenter

​token

​httpAuth

​tls

​prefix

​refreshInterval

​watch

​exposedByDefault

​defaultRule

​constraints

​Consistency Mode

​requireConsistent

​stale

​cache

​Consul Connect

​connectAware

​connectByDefault

​namespaces (Enterprise)

​strictChecks

​Complete Example

​Advanced Patterns

​Canary Deployments

​Multi-Datacenter Setup

​Service Mesh with Consul Connect

​Tag Syntax

​Troubleshooting

​Services Not Discovered

​Health Checks Failing

​ACL Errors

​Best Practices

​Next Steps

Routing Overview

Consul Documentation

Consul Catalog Provider

Quick Start

How It Works

Service Registration Examples

Basic HTTP Service

Service with Middleware

Multiple Routers per Service

Provider Configuration

endpoint

address

scheme

datacenter

token

httpAuth

tls

prefix

refreshInterval

watch

exposedByDefault

defaultRule

constraints

Consistency Mode

requireConsistent

stale

cache

Consul Connect

connectAware

connectByDefault

namespaces (Enterprise)

strictChecks

Complete Example

Advanced Patterns

Canary Deployments

Multi-Datacenter Setup

Service Mesh with Consul Connect

Tag Syntax

Troubleshooting

Services Not Discovered

Health Checks Failing

ACL Errors

Best Practices

Next Steps