Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/traefik/traefik/llms.txt

Use this file to discover all available pages before exploring further.

​
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

1

Enable Consul Catalog Provider

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

Register Service with Tags

{
  "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
}
3

Access Your Service

Traefik automatically detects the service and creates routes!

​
How It Works

The Consul Catalog provider:
  1. Polls Consul at regular intervals (or uses watch mode)
  2. Discovers services with tags matching the configured prefix
  3. Extracts routing configuration from service tags
  4. Creates routes dynamically
  5. 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"
  }
}

​
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`)"

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

​
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`)"
Register with datacenter tag: 
{
  "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"
Register Connect-enabled service: 
{
  "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: 
traefik.http.routers.app.rule=Host(`example.com`)
traefik.http.routers.app.middlewares=auth

​
Troubleshooting

​
Services Not Discovered

1

Check Consul Connection

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

Verify Service Tags

consul catalog services -tags
Ensure tags start with configured prefix.
3

Check exposedByDefault

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

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

1

Use Health Checks

Always configure Consul health checks for services.
2

Enable Watch Mode

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

Set Proper Consistency

Use stale: true for better performance in large deployments.
4

Tag Consistently

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

Secure Communication

Use TLS and ACL tokens for Consul connections.

​
Next Steps

Routing Overview

Learn about routing configuration

Consul Documentation

Official HashiCorp Consul documentation