Traefik & File

    The file provider lets you define the dynamic configuration in a TOML or YAML file. You can write one of these mutually exclusive configuration elements:

    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 location for common elements you'd like to re-use from other providers; e.g. declaring whitelist middlewares, basic authentication, …

    Declaring Routers, Middlewares & Services

    Enabling the file provider:

    2.   file:
    3.     directory: "/path/to/dynamic/conf"
    1. --providers.file.directory=/path/to/dynamic/conf
    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/"
    1. http:
    2.   # Add the router
    3.   routers:
    4.     router0:
    5.       entryPoints:
    6.       - web
    7.       - my-basic-auth
    8.       service: service-foo
    9.       rule: Path(`/foo`)
    11.   # Add the middleware
    12.   middlewares:
    13.     my-basic-auth:
    14.       basicAuth:
    16.         - test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
    17.         - test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0
    18.         usersFile: etc/traefik/.htpasswd
    20.   # Add the service
    21.   services:
    22.     service-foo:
    23.       loadBalancer:
    24.         servers:
    25.         - url: http://foo/
    26.         - url: http://bar/
    27.         passHostHeader: false

    Provider Configuration

    If you're in a hurry, maybe you'd rather go through the dynamic configuration references and the .

    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 will be broken and the container's file will not be updated. To avoid this kind of issue, a good practice is 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 use . If using a directory with a mounted directory does not fix your issue, please check your file system compatibility with fsnotify.

    Defines the path to the configuration file.

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

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

    filename and directory are mutually exclusive. The recommendation is to use directory.

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

    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.

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

    Warning

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

    Traefik allows using Go templating, it must be a valid Go template, augmented with the .

    Configuring Using Templating

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