1
0
Fork 0

Provider documentation fixes

This commit is contained in:
Brendan Le Glaunec 2021-02-11 19:04:03 +01:00 committed by GitHub
parent 5597d7633d
commit 0937cba870
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
15 changed files with 940 additions and 857 deletions

View file

@ -1,43 +1,43 @@
# Traefik & File
Good Old Configuration File
{: .subtitle }
{: .subtitle }
The file provider lets you define the [dynamic configuration](./overview.md) in a TOML or YAML file.
You can write one of these mutually exclusive configuration elements:
* In [a dedicated file](#filename)
* In [several dedicated files](#directory)
It supports providing configuration through a [single configuration file]](#filename) or [multiple separate files](#directory).
!!! info
The file provider is the default format used throughout the documentation to show samples of the configuration for many features.
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, ...
The file provider can be a good solution for reusing common elements from other providers (e.g. declaring whitelist middlewares, basic authentication, ...)
## Configuration Examples
??? example "Declaring Routers, Middlewares & Services"
Enabling the file provider:
```toml tab="File (TOML)"
[providers.file]
directory = "/path/to/dynamic/conf"
```
```yaml tab="File (YAML)"
providers:
file:
directory: "/path/to/dynamic/conf"
```
```bash tab="CLI"
--providers.file.directory=/path/to/dynamic/conf
```
Declaring Routers, Middlewares & Services:
```toml tab="TOML"
[http]
# Add the router
@ -47,14 +47,14 @@ You can write one of these mutually exclusive configuration elements:
middlewares = ["my-basic-auth"]
service = "service-foo"
rule = "Path(`/foo`)"
# Add the middleware
[http.middlewares]
[http.middlewares]
[http.middlewares.my-basic-auth.basicAuth]
users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
"test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"]
usersFile = "etc/traefik/.htpasswd"
# Add the service
[http.services]
[http.services.service-foo]
@ -64,7 +64,7 @@ You can write one of these mutually exclusive configuration elements:
[[http.services.service-foo.loadBalancer.servers]]
url = "http://bar/"
```
```yaml tab="YAML"
http:
# Add the router
@ -76,7 +76,7 @@ You can write one of these mutually exclusive configuration elements:
- my-basic-auth
service: service-foo
rule: Path(`/foo`)
# Add the middleware
middlewares:
my-basic-auth:
@ -85,7 +85,7 @@ You can write one of these mutually exclusive configuration elements:
- test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
- test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0
usersFile: etc/traefik/.htpasswd
# Add the service
services:
service-foo:
@ -98,31 +98,32 @@ You can write one of these mutually exclusive configuration elements:
## Provider Configuration
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).
For an overview of all the options that can be set with the file provider, see the [dynamic configuration](../reference/dynamic-configuration/file.md) and [static configuration](../reference/static-configuration/overview.md) references.
!!! 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:
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**](#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).
As it is very difficult to listen to all file system notifications, Traefik uses [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 to the configuration file.
!!! warning ""
`filename` and `directory` are mutually exclusive.
The recommendation is to use `directory`.
The `filename` and `directory` options are mutually exclusive.
It is recommended to use `directory`.
```toml tab="File (TOML)"
[providers]
@ -145,8 +146,9 @@ providers:
Defines the path to the directory that contains the configuration files.
!!! warning ""
`filename` and `directory` are mutually exclusive.
The recommendation is to use `directory`.
The `filename` and `directory` options are mutually exclusive.
It is recommended to use `directory`.
```toml tab="File (TOML)"
[providers]
@ -166,7 +168,7 @@ providers:
### `watch`
Set the `watch` option to `true` to allow Traefik to automatically watch for file changes.
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.
```toml tab="File (TOML)"
@ -191,63 +193,62 @@ providers:
### 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 portions of configuration files.
These sections must be valid [Go templates](https://golang.org/pkg/text/template/),
augmented with the [Sprig template functions](http://masterminds.github.io/sprig/).
Traefik supports using Go templating to automatically generate repetitive sections of configuration files.
These sections must be a valid [Go template](https://golang.org/pkg/text/template/), and can use
[sprig template functions](http://masterminds.github.io/sprig/).
To illustrate, it's possible to easily define multiple routers, services, and TLS certificates as described in the following examples:
To illustrate, it is possible to easily define multiple routers, services, and TLS certificates as described in the following examples:
??? example "Configuring Using Templating"
```toml tab="TOML"
# template-rules.toml
[http]
[http.routers]
{{ range $i, $e := until 100 }}
[http.routers.router{{ $e }}-{{ env "MY_ENV_VAR" }}]
# ...
{{ end }}
{{ end }}
[http.services]
{{ range $i, $e := until 100 }}
[http.services.service{{ $e }}]
# ...
{{ end }}
{{ end }}
[tcp]
[tcp.routers]
{{ range $i, $e := until 100 }}
[tcp.routers.router{{ $e }}]
# ...
{{ end }}
{{ end }}
[tcp.services]
{{ range $i, $e := until 100 }}
[http.services.service{{ $e }}]
# ...
{{ end }}
{{ end }}
{{ range $i, $e := until 10 }}
[[tls.certificates]]
certFile = "/etc/traefik/cert-{{ $e }}.pem"
keyFile = "/etc/traefik/cert-{{ $e }}.key"
stores = ["my-store-foo-{{ $e }}", "my-store-bar-{{ $e }}"]
{{ end }}
[tls.config]
{{ range $i, $e := until 10 }}
[tls.config.TLS{{ $e }}]
# ...
{{ end }}
```
```yaml tab="YAML"
http:
routers:
@ -255,26 +256,26 @@ To illustrate, it's possible to easily define multiple routers, services, and TL
router{{ $e }}-{{ env "MY_ENV_VAR" }}:
# ...
{{end}}
services:
{{range $i, $e := until 100 }}
application{{ $e }}:
# ...
{{end}}
tcp:
routers:
{{range $i, $e := until 100 }}
router{{ $e }}:
# ...
{{end}}
services:
{{range $i, $e := until 100 }}
service{{ $e }}:
# ...
{{end}}
tls:
certificates:
{{ range $i, $e := until 10 }}