1
0
mirror of https://github.com/containous/traefik.git synced 2024-12-23 17:34:13 +03:00
traefik/docs/content/providers/file.md

296 lines
7.9 KiB
Markdown
Raw Normal View History

---
title: "Traefik File Documentation"
description: "The file provider in Traefik Proxy lets you define the dynamic configuration in a YAML or TOML file. Read the technical documentation."
---
2019-03-14 18:46:05 +03:00
# Traefik & File
Good Old Configuration File
2021-02-11 21:04:03 +03:00
{: .subtitle }
The file provider lets you define the [dynamic configuration](./overview.md) in a YAML or TOML file.
It supports providing configuration through a [single configuration file](#filename) or [multiple separate files](#directory).
2019-09-23 15:32:04 +03:00
!!! info
2021-02-11 21:04:03 +03:00
The file provider is the default format used throughout the documentation to show samples of the configuration for many features.
2019-03-14 18:46:05 +03:00
!!! tip
2021-02-11 21:04:03 +03:00
2022-10-26 18:16:05 +03:00
The file provider can be a good solution for reusing common elements from other providers (e.g. declaring allowlist middlewares, basic authentication, ...)
2019-03-14 18:46:05 +03:00
## Configuration Examples
2019-03-14 18:46:05 +03:00
??? example "Declaring Routers, Middlewares & Services"
Enabling the file provider:
2021-02-11 21:04:03 +03:00
```yaml tab="File (YAML)"
providers:
file:
directory: "/path/to/dynamic/conf"
```
2021-02-11 21:04:03 +03:00
```toml tab="File (TOML)"
[providers.file]
directory = "/path/to/dynamic/conf"
```
```bash tab="CLI"
--providers.file.directory=/path/to/dynamic/conf
```
2021-02-11 21:04:03 +03:00
Declaring Routers, Middlewares & Services:
2021-02-11 21:04:03 +03:00
```yaml tab="YAML"
http:
2019-07-01 12:30:05 +03:00
# Add the router
routers:
router0:
2019-07-01 12:30:05 +03:00
entryPoints:
- web
middlewares:
- my-basic-auth
service: service-foo
2019-09-03 19:02:05 +03:00
rule: Path(`/foo`)
2021-02-11 21:04:03 +03:00
2019-07-01 12:30:05 +03:00
# Add the middleware
middlewares:
my-basic-auth:
basicAuth:
users:
- test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
- test2:$apr1$d9hr9HBB$4HxwgUir3HP4EsggP/QNo0
2019-07-01 12:30:05 +03:00
usersFile: etc/traefik/.htpasswd
2021-02-11 21:04:03 +03:00
2019-07-01 12:30:05 +03:00
# Add the service
services:
service-foo:
2019-07-01 12:30:05 +03:00
loadBalancer:
servers:
- url: http://foo/
- url: http://bar/
2019-07-01 12:30:05 +03:00
passHostHeader: false
```
```toml tab="TOML"
[http]
# Add the router
[http.routers]
[http.routers.router0]
entryPoints = ["web"]
middlewares = ["my-basic-auth"]
service = "service-foo"
rule = "Path(`/foo`)"
# Add the middleware
[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]
[http.services.service-foo.loadBalancer]
[[http.services.service-foo.loadBalancer.servers]]
url = "http://foo/"
[[http.services.service-foo.loadBalancer.servers]]
url = "http://bar/"
```
2019-09-23 15:32:04 +03:00
## Provider Configuration
2021-02-11 21:04:03 +03:00
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.
2019-04-24 18:44:04 +03:00
!!! warning "Limitations"
With the file provider, Traefik listens for file system notifications to update the dynamic configuration.
2021-02-11 21:04:03 +03:00
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.
2021-02-11 21:04:03 +03:00
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
2021-02-11 21:04:03 +03:00
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.
2021-02-11 21:04:03 +03:00
2019-09-23 15:32:04 +03:00
### `filename`
Defines the path to the configuration file.
!!! warning ""
2021-02-11 21:04:03 +03:00
The `filename` and `directory` options are mutually exclusive.
It is recommended to use `directory`.
2019-03-14 18:46:05 +03:00
```yaml tab="File (YAML)"
providers:
file:
filename: /path/to/config/dynamic_conf.yml
```
```toml tab="File (TOML)"
[providers]
[providers.file]
filename = "/path/to/config/dynamic_conf.toml"
```
```bash tab="CLI"
--providers.file.filename=/path/to/config/dynamic_conf.yml
```
2019-04-24 18:44:04 +03:00
### `directory`
Defines the path to the directory that contains the configuration files.
!!! warning ""
2021-02-11 21:04:03 +03:00
The `filename` and `directory` options are mutually exclusive.
It is recommended to use `directory`.
2019-03-14 18:46:05 +03:00
```yaml tab="File (YAML)"
providers:
file:
directory: /path/to/config
```
```toml tab="File (TOML)"
[providers]
[providers.file]
directory = "/path/to/config"
```
```bash tab="CLI"
--providers.file.directory=/path/to/config
```
2019-04-24 18:44:04 +03:00
### `watch`
2021-02-11 21:04:03 +03:00
Set the `watch` option to `true` to allow Traefik to automatically watch for file changes.
2019-03-14 18:46:05 +03:00
It works with both the `filename` and the `directory` options.
```yaml tab="File (YAML)"
providers:
file:
directory: /path/to/dynamic/conf
watch: true
```
```toml tab="File (TOML)"
[providers]
[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 18:46:05 +03:00
!!! warning
2021-02-11 21:04:03 +03:00
Go Templating only works with dedicated dynamic configuration files.
2019-09-23 15:32:04 +03:00
Templating does not work in the Traefik main static configuration file.
2019-03-14 18:46:05 +03:00
2021-02-11 21:04:03 +03:00
Traefik supports using Go templating to automatically generate repetitive sections of configuration files.
2021-09-10 12:42:07 +03:00
These sections must be a valid [Go template](https://pkg.go.dev/text/template/), and can use
2021-08-31 19:54:06 +03:00
[sprig template functions](https://masterminds.github.io/sprig/).
2021-02-11 21:04:03 +03:00
To illustrate, it is possible to easily define multiple routers, services, and TLS certificates as described in the following examples:
2019-03-14 18:46:05 +03:00
??? example "Configuring Using Templating"
2021-02-11 21:04:03 +03:00
```yaml tab="YAML"
http:
routers:
{{range $i, $e := until 100 }}
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 }}
- certFile: "/etc/traefik/cert-{{ $e }}.pem"
keyFile: "/etc/traefik/cert-{{ $e }}.key"
store:
- "my-store-foo-{{ $e }}"
- "my-store-bar-{{ $e }}"
{{end}}
```
```toml tab="TOML"
2019-03-14 18:46:05 +03:00
# template-rules.toml
[http]
2021-02-11 21:04:03 +03:00
2019-03-14 18:46:05 +03:00
[http.routers]
{{ range $i, $e := until 100 }}
[http.routers.router{{ $e }}-{{ env "MY_ENV_VAR" }}]
2019-03-14 18:46:05 +03:00
# ...
2021-02-11 21:04:03 +03:00
{{ end }}
2019-07-01 12:30:05 +03:00
[http.services]
2019-03-14 18:46:05 +03:00
{{ range $i, $e := until 100 }}
[http.services.service{{ $e }}]
# ...
2021-02-11 21:04:03 +03:00
{{ end }}
2019-03-14 18:46:05 +03:00
[tcp]
2021-02-11 21:04:03 +03:00
2019-03-14 18:46:05 +03:00
[tcp.routers]
{{ range $i, $e := until 100 }}
[tcp.routers.router{{ $e }}]
# ...
2021-02-11 21:04:03 +03:00
{{ end }}
2019-07-01 12:30:05 +03:00
[tcp.services]
2019-03-14 18:46:05 +03:00
{{ range $i, $e := until 100 }}
[http.services.service{{ $e }}]
# ...
2021-02-11 21:04:03 +03:00
{{ end }}
2019-03-14 18:46:05 +03:00
{{ range $i, $e := until 10 }}
[[tls.certificates]]
2019-07-01 12:30:05 +03:00
certFile = "/etc/traefik/cert-{{ $e }}.pem"
keyFile = "/etc/traefik/cert-{{ $e }}.key"
stores = ["my-store-foo-{{ $e }}", "my-store-bar-{{ $e }}"]
2019-03-14 18:46:05 +03:00
{{ end }}
2021-02-11 21:04:03 +03:00
[tls.config]
2019-03-14 18:46:05 +03:00
{{ range $i, $e := until 10 }}
[tls.config.TLS{{ $e }}]
2019-03-14 18:46:05 +03:00
# ...
{{ end }}
```
2022-09-09 18:17:53 +03:00
{!traefik-for-business-applications.md!}