Providers Configuration

Configure providers for automatic service discovery from Docker, Kubernetes, files, and other infrastructure sources.

Providers

Automatic Configuration Discovery

Providers are infrastructure components that Traefik queries to discover services and routing configuration. They enable dynamic configuration updates without manual intervention.

Provider Types

Traefik supports four types of providers:

Orchestrators

Docker, Kubernetes, Nomad, ECS - Discover services from container platforms

Key-Value Stores

Consul, Etcd, Redis, ZooKeeper - Store configuration in distributed KV stores

File-Based

YAML/TOML files - Define configuration manually in files

Service Discovery

Consul Catalog, Nomad - Discover services from service catalogs

Static vs Dynamic Configuration

Static Configuration (defined at startup):

• Which providers to enable
• Provider connection details
• Provider-specific settings

Dynamic Configuration (discovered from providers):

• Routers
• Services
• Middlewares
• TLS certificates

File Provider

Define configuration in YAML or TOML files:

Basic Configuration

YAML

providers:
  file:
    directory: "/etc/traefik/dynamic"
    watch: true

TOML

[providers.file]
  directory = "/etc/traefik/dynamic"
  watch = true

CLI

--providers.file.directory=/etc/traefik/dynamic \
--providers.file.watch=true

directory · string

Directory containing dynamic configuration files

filename · string

Single file containing dynamic configuration (alternative to directory)

watch · boolean · default: "true"

Automatically reload when files change

Example Dynamic Configuration File

/etc/traefik/dynamic/config.yml

http:
  routers:
    my-router:
      rule: "Host(`example.com`)"
      service: my-service
      tls:
        certResolver: letsencrypt

  services:
    my-service:
      loadBalancer:
        servers:
          - url: "http://192.168.1.10:8080"
          - url: "http://192.168.1.11:8080"

  middlewares:
    test-compress:
      compress: {}

Docker Provider

Automatically discover services from Docker containers:

Basic Configuration

YAML

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
    network: "traefik-network"
    watch: true

TOML

[providers.docker]
  endpoint = "unix:///var/run/docker.sock"
  exposedByDefault = false
  network = "traefik-network"
  watch = true

CLI

--providers.docker=true \
--providers.docker.endpoint=unix:///var/run/docker.sock \
--providers.docker.exposedByDefault=false \
--providers.docker.network=traefik-network

endpoint · string · default: "unix:///var/run/docker.sock"

Docker daemon socket or TCP endpoint

exposedByDefault · boolean · default: "true"

Automatically expose all containers (set to false for production)

network · string

Docker network to use for connections

watch · boolean · default: "true"

Watch for Docker events to update configuration

Container Labels

Configure routing using Docker labels:

docker-compose.yml

services:
  whoami:
    image: traefik/whoami
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.whoami.rule=Host(`whoami.example.com`)"
      - "traefik.http.routers.whoami.entrypoints=websecure"
      - "traefik.http.routers.whoami.tls.certresolver=letsencrypt"
      - "traefik.http.services.whoami.loadbalancer.server.port=80"

Kubernetes Providers

Kubernetes CRD Provider

Use Traefik’s Custom Resource Definitions:

YAML

providers:
  kubernetesCRD:
    endpoint: "https://kubernetes.default.svc"
    namespaces:
      - default
      - production

TOML

[providers.kubernetesCRD]
  endpoint = "https://kubernetes.default.svc"
  namespaces = ["default", "production"]

IngressRoute Example

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: myapp
  namespace: default
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`myapp.example.com`)
      kind: Rule
      services:
        - name: myapp
          port: 80
  tls:
    certResolver: letsencrypt

Kubernetes Ingress Provider

Use standard Kubernetes Ingress resources:

YAML

providers:
  kubernetesIngress:
    endpoint: "https://kubernetes.default.svc"
    namespaces:
      - default
      - production

TOML

[providers.kubernetesIngress]
  endpoint = "https://kubernetes.default.svc"
  namespaces = ["default", "production"]

Ingress Example

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: myapp
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    cert-manager.io/cluster-issuer: letsencrypt
spec:
  rules:
    - host: myapp.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: myapp
                port:
                  number: 80
  tls:
    - hosts:
        - myapp.example.com
      secretName: myapp-tls

HTTP Provider

Fetch configuration from HTTP endpoint:

YAML

providers:
  http:
    endpoint: "http://config-server/traefik.json"
    pollInterval: "5s"
    pollTimeout: "5s"

TOML

[providers.http]
  endpoint = "http://config-server/traefik.json"
  pollInterval = "5s"
  pollTimeout = "5s"

endpoint · string · required

HTTP endpoint returning JSON configuration

pollInterval · duration · default: "5s"

How often to poll for configuration updates

Multiple Providers

You can enable multiple providers simultaneously:

YAML

providers:
  # File-based configuration
  file:
    directory: "/etc/traefik/dynamic"
    watch: true
  
  # Docker containers
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
  
  # Kubernetes CRDs
  kubernetesCRD:
    endpoint: "https://kubernetes.default.svc"
  
  # Configuration reload throttling
  providersThrottleDuration: "2s"

TOML

[providers]
  providersThrottleDuration = "2s"
  
  [providers.file]
    directory = "/etc/traefik/dynamic"
    watch = true
  
  [providers.docker]
    endpoint = "unix:///var/run/docker.sock"
    exposedByDefault = false
  
  [providers.kubernetesCRD]
    endpoint = "https://kubernetes.default.svc"

Provider Namespaces

When referencing resources across providers, use the @provider syntax:

http:
  routers:
    my-router:
      rule: "Host(`example.com`)"
      service: my-service
      middlewares:
        - auth@file          # Middleware from file provider
        - compress@docker    # Middleware from Docker provider

The provider name is appended with @ to reference cross-provider resources.

Provider Reference

Provider	Type	Config Type	Provider Name
Docker	Orchestrator	Labels	docker
Kubernetes CRD	Orchestrator	Custom Resource	kubernetescrd
Kubernetes Ingress	Orchestrator	Ingress	kubernetes
Kubernetes Gateway	Orchestrator	Gateway API	kubernetesgateway
File	Manual	YAML/TOML	file
Consul	KV Store	Key-Value	consul
Etcd	KV Store	Key-Value	etcd
Redis	KV Store	Key-Value	redis
ZooKeeper	KV Store	Key-Value	zookeeper
HTTP	Manual	JSON	http
Consul Catalog	Service Discovery	Labels	consulcatalog
Nomad	Orchestrator	Labels	nomad
ECS	Orchestrator	Labels	ecs

Best Practices

Security

• Set exposedByDefault: false for Docker provider
• Use network isolation between Traefik and services
• Restrict provider API access with minimal permissions
• Validate configuration before applying

Performance

• Use providersThrottleDuration to avoid excessive reloads
• Filter namespaces in Kubernetes providers
• Use constraints to limit scope of service discovery
• Enable watch mode for real-time updates

Reliability

• Always define health checks for services
• Use multiple providers for redundancy
• Set appropriate timeouts for provider connections
• Monitor provider connection status

Complete Example

YAML

# traefik.yml - Static Configuration
providers:
  # Throttle configuration updates
  providersThrottleDuration: "2s"
  
  # File provider for static routes
  file:
    directory: "/etc/traefik/dynamic"
    watch: true
  
  # Docker provider for container discovery
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
    network: "traefik-public"
    watch: true
    constraints: "Label(`traefik.tags`, `production`)"
  
  # Kubernetes CRD provider
  kubernetesCRD:
    endpoint: "https://kubernetes.default.svc"
    namespaces:
      - production
      - staging
    labelSelector: "environment in (production, staging)"

TOML

# traefik.toml - Static Configuration
[providers]
  providersThrottleDuration = "2s"
  
  [providers.file]
    directory = "/etc/traefik/dynamic"
    watch = true
  
  [providers.docker]
    endpoint = "unix:///var/run/docker.sock"
    exposedByDefault = false
    network = "traefik-public"
    watch = true
    constraints = "Label(`traefik.tags`, `production`)"
  
  [providers.kubernetesCRD]
    endpoint = "https://kubernetes.default.svc"
    namespaces = ["production", "staging"]
    labelSelector = "environment in (production, staging)"