File / Directory provider

The simplest provider. Watches a single file or a whole directory and emits the parsed configuration whenever the contents change.

Source

pkg/provider/file/ — about a dozen Go files. The main types are in:

• pkg/provider/file/file.go — provider definition, watch loop, parsing.

Configuration

Static config:

providers:
  file:
    filename: /etc/traefik/dynamic.yml
    # or
    directory: /etc/traefik/dynamic.d/
    watch: true

Either filename or directory is set, not both. When directory is used, every file inside is read; YAML, TOML, and JSON are auto-detected from the extension.

watch: true activates an fsnotify watcher; updates produce a fresh dynamic.Message. With watch: false, the file is read once at startup.

What gets parsed

The file content is a dynamic.Configuration:

http:
  routers:
    my-router:
      rule: Host(`api.example.com`)
      service: my-service
      middlewares: ['my-mw']
  services:
    my-service:
      loadBalancer:
        servers:
          - url: http://backend:8080
  middlewares:
    my-mw:
      headers:
        customRequestHeaders:
          X-Foo: Bar
tls:
  certificates:
    - certFile: /etc/traefik/cert.pem
      keyFile: /etc/traefik/key.pem

The same struct is used by every other provider — the file provider's job is simply to deserialize and emit it.

Templating

File contents are processed by a Go template engine before parsing. Available helpers come from Masterminds/sprig plus a handful of Traefik-specific helpers. This lets you do things like:

http:
  services:
    {{ range $i := until 5 }}
    backend-{{ $i }}:
      loadBalancer:
        servers:
          - url: http://backend-{{ $i }}:80
    {{ end }}

Templating is opt-in: any file with the .tmpl extension is templated, others are parsed verbatim.

Watch loop

graph LR
    Cfg[Static config<br/>filename/directory] --> Init[file.go: Init]
    Init --> Read[read + parse]
    Read --> Send[send dynamic.Message]
    Init --> Watch[fsnotify watcher]
    Watch -->|change event| Debounce[debounce]
    Debounce --> Read

The provider debounces rapid filesystem events (multiple writes in quick succession produce only one configuration apply).

Use cases

• Quick experimentation: run Traefik with a single file you can edit live.
• Bridging providers: point another tool (Ansible, Salt, Helm) at a file and let Traefik pick up the result.
• Hand-written TLS material: tls.certificates is most ergonomically defined here.

For configuration that changes per-deployment-target, prefer Docker labels, Kubernetes resources, or a KV store — the file provider is best at static or rarely-changed configuration.

Other providers in this section: Docker, Kubernetes, KV stores, Consul Catalog, Nomad, ECS, HTTP, REST, Tailscale, ACME.