From 89db08eb93fd8cf66ac1948efb4e5bbaa421239f Mon Sep 17 00:00:00 2001 From: Jean-Baptiste Doumenjou Date: Mon, 9 Dec 2019 11:48:05 +0100 Subject: [PATCH] Improve documentation on file provider limitations with file system notifications --- docs/content/migration/v1-to-v2.md | 8 ++++---- docs/content/providers/file.md | 28 ++++++++++++++++++++++------ docs/content/routing/overview.md | 24 ++++++++++++------------ docs/content/user-guides/grpc.md | 16 ++++++++-------- 4 files changed, 46 insertions(+), 30 deletions(-) diff --git a/docs/content/migration/v1-to-v2.md b/docs/content/migration/v1-to-v2.md index 0ae0bbef5..ead0fc0e8 100644 --- a/docs/content/migration/v1-to-v2.md +++ b/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: diff --git a/docs/content/providers/file.md b/docs/content/providers/file.md index 747c2de1a..7fac1e95f 100644 --- a/docs/content/providers/file.md +++ b/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 ``` diff --git a/docs/content/routing/overview.md b/docs/content/routing/overview.md index 8808e0a48..c66cdb161 100644 --- a/docs/content/routing/overview.md +++ b/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** diff --git a/docs/content/user-guides/grpc.md b/docs/content/user-guides/grpc.md index 6c8979dec..3fef7d420 100644 --- a/docs/content/user-guides/grpc.md +++ b/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 ##