traefik/docs/content/providers/file.md

279 lines
7.3 KiB
Markdown
Raw Normal View History

2019-03-14 15:46:05 +00:00
# Traefik & File
Good Old Configuration File
{: .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:
2019-04-24 15:44:04 +00:00
* In [a dedicated file](#filename)
* In [several dedicated files](#directory)
2019-09-23 12:32:04 +00:00
!!! info
2019-03-14 15:46:05 +00:00
The file provider is the default format used throughout the documentation to show samples of the configuration for many features.
2019-03-14 15:46:05 +00:00
!!! 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, ...
2019-03-14 15:46:05 +00:00
## Configuration Examples
2019-03-14 15:46:05 +00:00
??? example "Declaring Routers, Middlewares & Services"
Enabling the file provider:
```toml tab="File (TOML)"
2019-03-21 14:34:04 +00:00
[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
```
2019-03-14 15:46:05 +00:00
Declaring Routers, Middlewares & Services:
```toml tab="TOML"
2019-03-14 15:46:05 +00:00
[http]
# Add the router
[http.routers]
[http.routers.router0]
entryPoints = ["web"]
2019-03-14 15:46:05 +00:00
middlewares = ["my-basic-auth"]
service = "service-foo"
2019-09-03 16:02:05 +00:00
rule = "Path(`/foo`)"
2019-03-14 15:46:05 +00:00
# Add the middleware
[http.middlewares]
2019-07-01 09:30:05 +00:00
[http.middlewares.my-basic-auth.basicAuth]
2019-03-14 15:46:05 +00:00
users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/",
"test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0"]
usersFile = "etc/traefik/.htpasswd"
# Add the service
[http.services]
[http.services.service-foo]
2019-07-01 09:30:05 +00:00
[http.services.service-foo.loadBalancer]
[[http.services.service-foo.loadBalancer.servers]]
2019-03-14 15:46:05 +00:00
url = "http://foo/"
2019-07-01 09:30:05 +00:00
[[http.services.service-foo.loadBalancer.servers]]
2019-03-14 15:46:05 +00:00
url = "http://bar/"
```
```yaml tab="YAML"
http:
2019-07-01 09:30:05 +00:00
# Add the router
routers:
router0:
2019-07-01 09:30:05 +00:00
entryPoints:
- web
middlewares:
- my-basic-auth
service: service-foo
2019-09-03 16:02:05 +00:00
rule: Path(`/foo`)
2019-07-01 09:30:05 +00:00
# Add the middleware
middlewares:
my-basic-auth:
basicAuth:
users:
- test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
- test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0
2019-07-01 09:30:05 +00:00
usersFile: etc/traefik/.htpasswd
# Add the service
services:
service-foo:
2019-07-01 09:30:05 +00:00
loadBalancer:
servers:
- url: http://foo/
- url: http://bar/
2019-07-01 09:30:05 +00:00
passHostHeader: false
```
2019-09-23 12:32:04 +00:00
## Provider Configuration
2019-09-23 12:32:04 +00:00
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).
2019-04-24 15:44:04 +00:00
!!! 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.
2019-09-23 12:32:04 +00:00
### `filename`
2019-03-14 15:46:05 +00:00
Defines the path of the configuration file.
```toml tab="File (TOML)"
2019-03-14 15:46:05 +00:00
[providers]
[providers.file]
filename = "dynamic_conf.toml"
2019-03-14 15:46:05 +00:00
```
```yaml tab="File (YAML)"
providers:
file:
filename: dynamic_conf.yml
```
```bash tab="CLI"
--providers.file.filename=dynamic_conf.toml
```
2019-04-24 15:44:04 +00:00
### `directory`
2019-03-14 15:46:05 +00:00
Defines the directory that contains the configuration files.
```toml tab="File (TOML)"
2019-03-14 15:46:05 +00:00
[providers]
[providers.file]
directory = "/path/to/config"
```
```yaml tab="File (YAML)"
providers:
file:
directory: /path/to/config
```
```bash tab="CLI"
--providers.file.directory=/path/to/config
```
2019-04-24 15:44:04 +00:00
### `watch`
2019-03-14 15:46:05 +00:00
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)"
2019-03-14 15:46:05 +00:00
[providers]
[providers.file]
directory = "/path/to/dynamic/conf"
2019-03-14 15:46:05 +00:00
watch = true
```
```yaml tab="File (YAML)"
providers:
file:
directory: /path/to/dynamic/conf
watch: true
```
```bash tab="CLI"
--providers.file.directory=/my/path/to/dynamic/conf
--providers.file.watch=true
```
### Go Templating
2019-03-14 15:46:05 +00:00
!!! warning
2019-09-23 12:32:04 +00:00
Go Templating only works along with dedicated dynamic configuration files.
Templating does not work in the Traefik main static configuration file.
2019-03-14 15:46:05 +00:00
Traefik allows using Go templating.
2019-03-14 15:46:05 +00:00
Thus, it's possible to define easily lot of routers, services and TLS certificates as described in the file `template-rules.toml` :
??? example "Configuring Using Templating"
```toml tab="TOML"
2019-03-14 15:46:05 +00:00
# template-rules.toml
[http]
[http.routers]
{{ range $i, $e := until 100 }}
[http.routers.router{{ $e }}]
# ...
{{ end }}
2019-07-01 09:30:05 +00:00
[http.services]
2019-03-14 15:46:05 +00:00
{{ range $i, $e := until 100 }}
[http.services.service{{ $e }}]
# ...
{{ end }}
[tcp]
[tcp.routers]
{{ range $i, $e := until 100 }}
[tcp.routers.router{{ $e }}]
# ...
{{ end }}
2019-07-01 09:30:05 +00:00
[tcp.services]
2019-03-14 15:46:05 +00:00
{{ range $i, $e := until 100 }}
[http.services.service{{ $e }}]
# ...
{{ end }}
{{ range $i, $e := until 10 }}
[[tls.certificates]]
2019-07-01 09:30:05 +00:00
certFile = "/etc/traefik/cert-{{ $e }}.pem"
keyFile = "/etc/traefik/cert-{{ $e }}.key"
store = ["my-store-foo-{{ $e }}", "my-store-bar-{{ $e }}"]
2019-03-14 15:46:05 +00:00
{{ end }}
[tls.config]
2019-03-14 15:46:05 +00:00
{{ range $i, $e := until 10 }}
[tls.config.TLS{{ $e }}]
2019-03-14 15:46:05 +00:00
# ...
{{ end }}
```
```yaml tab="YAML"
http:
{{range $i, $e := until 100 }}
routers:
router{{ $e }:
# ...
{{end}}
{{range $i, $e := until 100 }}
services:
application{{ $e }}:
# ...
{{end}}
tcp:
{{range $i, $e := until 100 }}
routers:
router{{ $e }:
# ...
{{end}}
{{range $i, $e := until 100 }}
services:
service{{ $e }}:
# ...
{{end}}
{{ range $i, $e := until 10 }}
tls:
certificates:
2019-07-01 09:30:05 +00:00
- certFile: "/etc/traefik/cert-{{ $e }}.pem"
keyFile: "/etc/traefik/cert-{{ $e }}.key"
store:
- "my-store-foo-{{ $e }}"
- "my-store-bar-{{ $e }}"
{{end}}
```