Improve documentation on file provider limitations with file system notifications
This commit is contained in:
parent
f40cf2cd8e
commit
89db08eb93
4 changed files with 46 additions and 30 deletions
|
@ -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:
|
||||
|
|
|
@ -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
|
||||
```
|
||||
|
||||
|
|
|
@ -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**
|
||||
|
|
|
@ -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 ##
|
||||
|
|
Loading…
Reference in a new issue