Traefik & File

Good Old Configuration File

The file provider lets you define the dynamic configuration in a YAML or TOML file.

It supports providing configuration through a single configuration file or multiple separate files.

Info

The file provider is the default format used throughout the documentation to show samples of the configuration for many features.

Tip

The file provider can be a good solution for reusing common elements from other providers (e.g. declaring allowlist middlewares, basic authentication, …)

Configuration Examples

Declaring Routers, Middlewares & Services

Enabling the file provider:

File (YAML)

  1. providers:
  2.   file:
  3.     directory: "/path/to/dynamic/conf"

File (TOML)

  1. [providers.file]
  2.   directory = "/path/to/dynamic/conf"

CLI

  1. --providers.file.directory=/path/to/dynamic/conf

Declaring Routers, Middlewares & Services:

YAML

  1. http:
  2.   # Add the router
  3.   routers:
  4.     router0:
  5.       entryPoints:
  6.       - web
  7.       middlewares:
  8.       - my-basic-auth
  9.       service: service-foo
  10.       rule: Path(`/foo`)
  12.   # Add the middleware
  13.   middlewares:
  14.     my-basic-auth:
  15.       basicAuth:
  16.         users:
  17.         - test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
  18.         - test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0
  19.         usersFile: etc/traefik/.htpasswd
  21.   # Add the service
  22.   services:
  23.     service-foo:
  24.       loadBalancer:
  25.         servers:
  26.         - url: http://foo/
  27.         - url: http://bar/
  28.         passHostHeader: false

TOML

  1. [http]
  2.   # Add the router
  3.   [http.routers]
  4.     [http.routers.router0]
  5.       entryPoints = ["web"]
  6.       middlewares = ["my-basic-auth"]
  7.       service = "service-foo"
  8.       rule = "Path(`/foo`)"
  10.   # Add the middleware
  11.   [http.middlewares]
  12.     [http.middlewares.my-basic-auth.basicAuth]
  13.       users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
  14.                 "test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"]
  15.       usersFile = "etc/traefik/.htpasswd"
  17.   # Add the service
  18.   [http.services]
  19.     [http.services.service-foo]
  20.       [http.services.service-foo.loadBalancer]
  21.         [[http.services.service-foo.loadBalancer.servers]]
  22.           url = "http://foo/"
  23.         [[http.services.service-foo.loadBalancer.servers]]
  24.           url = "http://bar/"

Provider Configuration

For an overview of all the options that can be set with the file provider, see the dynamic configuration and static configuration references.

Limitations

With the file provider, Traefik listens for file system notifications to update the dynamic configuration.

If you use a mounted/bound file system in your orchestrator (like docker or kubernetes), the way the files are linked may be a source of errors. If the link between the file systems is broken, when a source file/directory is changed/renamed, nothing will be reported to the linked file/directory, so the file system notifications will be neither triggered nor caught.

For example, in Docker, if the host file is renamed, the link to the mounted file is broken and the container’s file is no longer updated. To avoid this kind of issue, it is recommended to:

  • set the Traefik directory configuration with the parent directory
  • mount/bind the parent directory

As it is very difficult to listen to all file system notifications, Traefik uses fsnotify. If using a directory with a mounted directory does not fix your issue, please check your file system compatibility with fsnotify.

filename

Defines the path to the configuration file.

The filename and directory options are mutually exclusive. It is recommended to use directory.

File (YAML)

  1. providers:
  2.   file:
  3.     filename: /path/to/config/dynamic_conf.yml

File (TOML)

  1. [providers]
  2.   [providers.file]
  3.     filename = "/path/to/config/dynamic_conf.toml"

CLI

  1. --providers.file.filename=/path/to/config/dynamic_conf.yml

directory

Defines the path to the directory that contains the configuration files.

The filename and directory options are mutually exclusive. It is recommended to use directory.

File (YAML)

  1. providers:
  2.   file:
  3.     directory: /path/to/config

File (TOML)

  1. [providers]
  2.   [providers.file]
  3.     directory = "/path/to/config"

CLI

  1. --providers.file.directory=/path/to/config

watch

Set the watch option to true to allow Traefik to automatically watch for file changes. It works with both the filename and the directory options.

File (YAML)

  1. providers:
  2.   file:
  3.     directory: /path/to/dynamic/conf
  4.     watch: true

File (TOML)

  1. [providers]
  2.   [providers.file]
  3.     directory = "/path/to/dynamic/conf"
  4.     watch = true

CLI

  1. --providers.file.directory=/my/path/to/dynamic/conf
  2. --providers.file.watch=true

Go Templating

Warning

Go Templating only works with dedicated dynamic configuration files. Templating does not work in the Traefik main static configuration file.

Traefik supports using Go templating to automatically generate repetitive sections of configuration files. These sections must be a valid Go template, and can use sprig template functions.

To illustrate, it is possible to easily define multiple routers, services, and TLS certificates as described in the following examples:

Configuring Using Templating

YAML

  1. http:
  2.   routers:
  3.     {{range $i, $e := until 100 }}
  4.     router{{ $e }}-{{ env "MY_ENV_VAR" }}:
  5.       # ...
  6.     {{end}}
  8.   services:
  9.     {{range $i, $e := until 100 }}
  10.     application{{ $e }}:
  11.       # ...
  12.     {{end}}
  14. tcp:
  15.   routers:
  16.     {{range $i, $e := until 100 }}
  17.     router{{ $e }}:
  18.       # ...
  19.     {{end}}
  21.   services:
  22.     {{range $i, $e := until 100 }}
  23.     service{{ $e }}:
  24.       # ...
  25.     {{end}}
  27. tls:
  28.   certificates:
  29.   {{ range $i, $e := until 10 }}
  30.   - certFile: "/etc/traefik/cert-{{ $e }}.pem"
  31.     keyFile: "/etc/traefik/cert-{{ $e }}.key"
  32.     store:
  33.     - "my-store-foo-{{ $e }}"
  34.     - "my-store-bar-{{ $e }}"
  35.   {{end}}

TOML

  1. # template-rules.toml
  2. [http]
  4.   [http.routers]
  5.   {{ range $i, $e := until 100 }}
  6.     [http.routers.router{{ $e }}-{{ env "MY_ENV_VAR" }}]
  7.     # ...
  8.   {{ end }}
  10.   [http.services]
  11.   {{ range $i, $e := until 100 }}
  12.       [http.services.service{{ $e }}]
  13.       # ...
  14.   {{ end }}
  16. [tcp]
  18.   [tcp.routers]
  19.   {{ range $i, $e := until 100 }}
  20.     [tcp.routers.router{{ $e }}]
  21.     # ...
  22.   {{ end }}
  24.   [tcp.services]
  25.   {{ range $i, $e := until 100 }}
  26.       [http.services.service{{ $e }}]
  27.       # ...
  28.   {{ end }}
  30. {{ range $i, $e := until 10 }}
  31. [[tls.certificates]]
  32.   certFile = "/etc/traefik/cert-{{ $e }}.pem"
  33.   keyFile = "/etc/traefik/cert-{{ $e }}.key"
  34.   stores = ["my-store-foo-{{ $e }}", "my-store-bar-{{ $e }}"]
  35. {{ end }}
  37. [tls.config]
  38. {{ range $i, $e := until 10 }}
  39.   [tls.config.TLS{{ $e }}]
  40.   # ...
  41. {{ end }}

Using Traefik for Business Applications?

If you are using Traefik in your organization, consider our enterprise-grade solutions:

These tools help businesses discover, deploy, secure, and manage microservices and APIs easily, at scale, across any environment.