Improve documentation on file provider limitations with file system notifications

docs/content/migration/v1-to-v2.md

@@ -1029,12 +1029,12 @@ As the dashboard access is now secured by default you can either:
     [api]
 
     [providers.file]
-      filename = "/dynamic-conf.toml"
+      directory = "/path/to/dynamic/config"
 
     ##---------------------##
 
     ## dynamic configuration
-    # dynamic-conf.toml
+    # /path/to/dynamic/config/dynamic-conf.toml
 
     [http.routers.api]
       rule = "Host(`traefik.docker.localhost`)"
@@ -1061,12 +1061,12 @@ As the dashboard access is now secured by default you can either:
 
     providers:
       file:
-        filename: /dynamic-conf.yaml
+        directory: /path/to/dynamic/config
 
     ##---------------------##
 
     ## dynamic configuration
-    # dynamic-conf.yaml
+    # /path/to/dynamic/config/dynamic-conf.yaml
 
      http:
       routers:

docs/content/providers/file.md

@@ -23,17 +23,17 @@ You can write one of these mutually exclusive configuration elements:
 
     ```toml tab="File (TOML)"
     [providers.file]
-      filename = "/my/path/to/dynamic-conf.toml"
+      directory = "/path/to/dynamic/conf"
     ```
 
     ```yaml tab="File (YAML)"
     providers:
       file:
-        filename: "/my/path/to/dynamic-conf.yml"
+        directory: "/path/to/dynamic/conf"
     ```
 
     ```bash tab="CLI"
-    --providers.file.filename=/my/path/to/dynamic_conf.toml
+    --providers.file.directory=/path/to/dynamic/conf
     ```
 
     Declaring Routers, Middlewares & Services:
@@ -100,6 +100,22 @@ You can write one of these mutually exclusive configuration elements:
 
 If you're in a hurry, maybe you'd rather go through the [dynamic configuration](../reference/dynamic-configuration/file.md) references and the [static configuration](../reference/static-configuration/overview.md).
 
+!!! warning "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**](#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 [fsnotify](https://github.com/fsnotify/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 of the configuration file.
@@ -148,19 +164,19 @@ It works with both the `filename` and the `directory` options.
 ```toml tab="File (TOML)"
 [providers]
   [providers.file]
-    filename = "dynamic_conf.toml"
+    directory = "/path/to/dynamic/conf"
     watch = true
 ```
 
 ```yaml tab="File (YAML)"
 providers:
   file:
-    filename: dynamic_conf.yml
+    directory: /path/to/dynamic/conf
     watch: true
 ```
 
 ```bash tab="CLI"
---providers.file.filename=dynamic_conf.toml
+--providers.file.directory=/my/path/to/dynamic/conf
 --providers.file.watch=true
 ```
 

docs/content/routing/overview.md

@@ -33,9 +33,9 @@ Static configuration:
     address = ":8081"
 
 [providers]
-  # Enable the file provider to define routers / middlewares / services in a file
+  # Enable the file provider to define routers / middlewares / services in file
   [providers.file]
-    filename = "dynamic_conf.toml"
+    directory = "/path/to/dynamic/conf"
 ```
 
 ```yaml tab="File (YAML)"
@@ -45,17 +45,17 @@ entryPoints:
     address: :8081
 
 providers:
-  # Enable the file provider to define routers / middlewares / services in a file
+  # Enable the file provider to define routers / middlewares / services in file
   file:
-    filename: dynamic_conf.yml
+    directory: /path/to/dynamic/conf
 ```
 
 ```bash tab="CLI"
 # Listen on port 8081 for incoming requests
 --entryPoints.web.address=:8081
 
-# Enable the file provider to define routers / middlewares / services in a file
---providers.file.filename=dynamic_conf.toml
+# Enable the file provider to define routers / middlewares / services in file
+--providers.file.directory=/path/to/dynamic/conf
 ```
 
 Dynamic configuration:
@@ -133,9 +133,9 @@ http:
             address = ":8081"
 
         [providers]
-          # Enable the file provider to define routers / middlewares / services in a file
+          # Enable the file provider to define routers / middlewares / services in file
           [providers.file]
-            filename = "dynamic_conf.toml"
+            directory = "/path/to/dynamic/conf"
         ```
 
         ```yaml tab="File (YAML)"
@@ -144,17 +144,17 @@ http:
             # Listen on port 8081 for incoming requests
             address: :8081
         providers:
-          # Enable the file provider to define routers / middlewares / services in a file
+          # Enable the file provider to define routers / middlewares / services in file
           file:
-            filename: dynamic_conf.yml
+            directory: /path/to/dynamic/conf
         ```
 
         ```bash tab="CLI"
         # Listen on port 8081 for incoming requests
         --entryPoints.web.address=:8081
 
-        # Enable the file provider to define routers / middlewares / services in a file
-        --providers.file.filename=dynamic_conf.toml
+        # Enable the file provider to define routers / middlewares / services in file
+        --providers.file.directory=/path/to/dynamic/conf
         ```
 
         **Dynamic Configuration**

docs/content/user-guides/grpc.md

@@ -16,7 +16,7 @@ Static configuration:
 [api]
 
 [providers.file]
-  filename = "dynamic_conf.toml"
+  directory = "/path/to/dynamic/config"
 ```
 
 ```yaml tab="File (YAML)"
@@ -26,18 +26,18 @@ entryPoints:
 
 providers:
   file:
-    filename: dynamic_conf.yml
+    directory: /path/to/dynamic/config
 
 api: {}
 ```
 
 ```yaml tab="CLI"
 --entryPoints.web.address=:80
---providers.file.filename=dynamic_conf.toml
+--providers.file.directory=/path/to/dynamic/config
 --api.insecure=true
 ```
 
-`dynamic_conf.{toml,yml}`:
+`/path/to/dynamic/config/dynamic_conf.{toml,yml}`:
 
 ```toml tab="TOML"
 ## dynamic configuration ##
@@ -132,7 +132,7 @@ Static configuration:
 [api]
 
 [provider.file]
-  filename = "dynamic_conf.toml"
+  directory = "/path/to/dynamic/config"
 ```
 
 ```yaml tab="File (YAML)"
@@ -147,7 +147,7 @@ serversTransport:
 
 providers:
   file:
-    filename: dynamic_conf.yml
+    directory: /path/to/dynamic/config
 
 api: {}
 ```
@@ -156,11 +156,11 @@ api: {}
 --entryPoints.websecure.address=:4443
 # For secure connection on backend.local
 --serversTransport.rootCAs=./backend.cert
---providers.file.filename=dynamic_conf.toml
+--providers.file.directory=/path/to/dynamic/config
 --api.insecure=true
 ```
 
-`dynamic_conf.{toml,yml}`:
+`/path/to/dynamic/config/dynamic_conf.{toml,yml}`:
 
 ```toml tab="TOML"
 ## dynamic configuration ##