Learn Traefik - File Provider & Dynamic Configuration

#Introduction

So far, dynamic configuration has come from Docker labels. But what about services that do not live in Docker — bare-metal servers, VMs, or applications with static backends? Episode 19 answers with the file provider: writing routers, services, and middlewares in YAML/TOML files that Traefik reads directly.

Its biggest advantage is the same as other providers: hot reload. Traefik watches the files and applies changes without a restart. Combined with an explicit structure that is easy to version-control, the file provider is the primary choice for complex and hybrid configurations.

#Setting Up the File Provider

#Directory Watching

The file provider is defined in static config, pointing to a directory or a single file:

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

• directory: the folder containing dynamic configuration files.
• watch: true: Traefik monitors changes and reloads automatically.

Every .yml, .yaml, or .toml file in that directory is read as one dynamic configuration block. Multiple files are allowed; Traefik merges them all. The file name is used as the log label — give descriptive names like routers.yml, middlewares.yml, certificates.yml.

#Dynamic File Structure

#The Four Main Sections

The top-level structure of a dynamic file mirrors the protocol split:

• http: routers, services, middlewares for HTTP.
• tcp: routers and services for TCP.
• udp: routers and services for UDP.
• tls: certificates and options.

A complete example for two services:

http:
  routers:
    blog:
      rule: "Host(`blog.example.com`)"
      entrypoints:
        - web
        - websecure
      service: blog-svc
      middlewares:
        - secure-headers
    api:
      rule: "Host(`api.example.com`) && PathPrefix(`/v2`)"
      entrypoints:
        - websecure
      service: api-svc
      tls: {}
  services:
    blog-svc:
      loadBalancer:
        servers:
          - url: "http://192.168.1.20:8080"
        healthCheck:
          path: "/health"
          interval: "20s"
    api-svc:
      loadBalancer:
        servers:
          - url: "http://192.168.1.21:3000"
          - url: "http://192.168.1.22:3000"
  middlewares:
    secure-headers:
      headers:
        frameDeny: true
        contentTypeNosniff: true

Note that the servers are static IPs without Docker — this is the power of the file provider for hybrid infrastructure.

#Dynamic Configuration

#Hot Reload and Validation

When a file changes, Traefik immediately validates and applies the new configuration. If a file contains syntax errors or broken references, Traefik rejects that update and keeps the previous valid configuration — no downtime because of a typo.

Verify that changes were accepted through the logs or the API:

docker logs traefik
curl -s http://localhost:8080/api/http/routers

A log message like Configuration loaded from file indicates a successful reload. The /api/http/routers API endpoint shows the currently active routers. The curl command is a quick way to confirm file changes are really applied before moving on.

#Error Handling

Errors that often appear when working with many files:

• Cross-file references: a router in one file references a service in another file — allowed, because Traefik merges all files into one namespace.
• Duplicate names: two files define a component with the same name — the last one loaded wins. Avoid this with consistent naming.
• YAML indentation: the most common error; use a YAML linter before deploying.

#Use Cases and Best Practices

#When to Use the File Provider

• Non-containerized services: backends on VMs or bare metal.
• Manual configuration: full control without an automation layer.
• Complex routing: combined rules and middlewares that are hard to express in labels.
• Static services: backends that rarely change.

#Best Practices

• Organize per service: one file per service domain, not one giant file.
• Version control: keep all dynamic files in git along with the infrastructure.
• Templating: for many environments, use templating then render at deploy time.
• Validate before deploying: test YAML with a local parser and run traefik checkConfig before applying to production.

#Closing

Key takeaways:

• The file provider reads YAML/TOML from a directory with watch: true.
• File structure: the http, tcp, udp, and tls sections.
• Hot reload applies; broken files are rejected without disturbing the old configuration.
• Routers can reference services across files in a single namespace.
• The file provider is ideal for non-container services and complex routing.
• Keep files in version control and validate before deploying.

In episode 20 next we enter the Kubernetes phase: kubernetes provider ingress — IngressClass and Ingress resources, host and path-based routing, the traefik.ingress.kubernetes.io/* annotations, TLS with Secrets and cert-manager, and Kubernetes Service types. Traefik works differently in the orchestrator world.