Configuration Overview

Learn about Traefik configuration fundamentals including static vs dynamic configuration, file formats, and configuration discovery.

Configuration Overview

Understanding Traefik’s Configuration Model

Traefik uses a dual configuration model that separates startup configuration from runtime routing configuration. This separation enables dynamic updates without service restarts.

Static vs Dynamic Configuration

Static Configuration

Static configuration defines Traefik’s startup behavior and cannot be changed without restarting Traefik. It includes:

• EntryPoints - Network ports where Traefik listens for incoming traffic
• Providers - Sources from which Traefik discovers dynamic configuration
• API and Dashboard - Built-in management interfaces
• Certificate Resolvers - ACME/Let’s Encrypt configuration
• Logging and Metrics - Observability settings

Static configuration is loaded once at startup from:

• Configuration file (YAML or TOML)
• Command-line arguments
• Environment variables

Dynamic Configuration

Dynamic configuration defines how requests are routed to services and can be updated without restarting Traefik:

• Routers - Connect incoming requests to services based on rules
• Services - Define backend servers and load balancing
• Middlewares - Process requests before forwarding to services
• TLS Certificates - SSL/TLS certificates for secure connections

Dynamic configuration is discovered through Providers and updates automatically when changes are detected.

The separation between static and dynamic configuration is fundamental to Traefik’s architecture. Static configuration sets up the infrastructure, while dynamic configuration handles the routing logic.

Configuration File Formats

Traefik supports two file formats for configuration:

YAML Format

Static Configuration (traefik.yml)

global:
  checkNewVersion: true
  sendAnonymousUsage: true

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

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

api:
  dashboard: true
  insecure: false

log:
  level: "INFO"

TOML Format

Static Configuration (traefik.toml)

[global]
  checkNewVersion = true
  sendAnonymousUsage = true

[entryPoints]
  [entryPoints.web]
    address = ":80"
  [entryPoints.websecure]
    address = ":443"

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

[api]
  dashboard = true
  insecure = false

[log]
  level = "INFO"

Configuration Sections

Global Configuration

The global section controls Traefik’s overall behavior:

checkNewVersion · boolean · default: "true"

Periodically check if a new version is available

sendAnonymousUsage · boolean · default: "true"

Send anonymous usage statistics to help improve Traefik

Example: Complete Static Configuration

YAML

global:
  checkNewVersion: true
  sendAnonymousUsage: true

entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  
  websecure:
    address: ":443"
    http:
      tls:
        certResolver: letsencrypt

certificatesResolvers:
  letsencrypt:
    acme:
      email: [e-mail]
      storage: /etc/traefik/acme.json
      httpChallenge:
        entryPoint: web

providers:
  docker:
    exposedByDefault: false
  file:
    directory: /etc/traefik/dynamic
    watch: true

api:
  dashboard: true

log:
  level: INFO
  format: json

accessLog:
  format: json

TOML

[global]
  checkNewVersion = true
  sendAnonymousUsage = true

[entryPoints]
  [entryPoints.web]
    address = ":80"
    [entryPoints.web.http.redirections.entryPoint]
      to = "websecure"
      scheme = "https"
  
  [entryPoints.websecure]
    address = ":443"
    [entryPoints.websecure.http.tls]
      certResolver = "letsencrypt"

[certificatesResolvers.letsencrypt]
  [certificatesResolvers.letsencrypt.acme]
    email = "[e-mail]"
    storage = "/etc/traefik/acme.json"
    [certificatesResolvers.letsencrypt.acme.httpChallenge]
      entryPoint = "web"

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

[api]
  dashboard = true

[log]
  level = "INFO"
  format = "json"

[accessLog]
  format = "json"

Configuration Priority

When using multiple configuration sources, Traefik applies them in this order (later sources override earlier ones):

1. Default values
2. Configuration file
3. Environment variables
4. Command-line arguments

For security reasons, avoid putting sensitive data (like API keys or passwords) directly in configuration files. Use environment variables or secrets management instead.

Configuration Validation

Traefik validates configuration on startup. If errors are found:

• Static Configuration Errors - Traefik will not start
• Dynamic Configuration Errors - Errors are logged, invalid configuration is ignored

Common Validation Errors

• Duplicate router/service names
• Invalid rule syntax
• Missing required fields
• Invalid port numbers or addresses
• Malformed TLS certificates

Next Steps

EntryPoints

Configure network entry points for incoming traffic

Routers

Define routing rules to connect requests to services

Services

Configure backend services and load balancing

Providers

Set up configuration discovery sources