Sheddy
42 KiB
title, description
| title | description |
|---|---|
| Traefik File Routing Configuration | This guide will provide you with the reference for file-based routing configuration in Traefik Proxy. Read the technical documentation. |
Traefik File Routing Configuration
The file provider lets you define routing configuration in YAML or TOML. Use it to declare routers, services, middlewares, TCP and UDP routing, and TLS options that Traefik should load from a file or a directory.
To configure the file provider itself, see the File provider install configuration page.
Configuration Examples
??? example "Configuring the File Provider and Exposing One HTTP Service"
Enabling the file provider:
```yaml tab="Structured (YAML)"
providers:
file:
filename: /etc/traefik/dynamic.yml
```
```toml tab="Structured (TOML)"
[providers.file]
filename = "/etc/traefik/dynamic.toml"
```
```bash tab="CLI"
--providers.file.filename=/etc/traefik/dynamic.yml
```
Declaring the dynamic HTTP configuration:
```yaml tab="Structured (YAML)"
http:
routers:
app:
rule: Host(`example.com`)
entryPoints:
- websecure
service: app
tls: {}
services:
app:
loadBalancer:
servers:
- url: http://127.0.0.1:8080
```
```toml tab="Structured (TOML)"
[http.routers.app]
rule = "Host(`example.com`)"
entryPoints = ["websecure"]
service = "app"
[http.routers.app.tls]
[http.services.app.loadBalancer]
[[http.services.app.loadBalancer.servers]]
url = "http://127.0.0.1:8080"
```
??? example "Specifying More Than One Router and Service"
Define each router and explicitly attach it to the service that should handle matching requests.
```yaml tab="Structured (YAML)"
http:
routers:
app:
rule: Host(`example-a.com`)
service: app
admin:
rule: Host(`example-b.com`)
service: admin
services:
app:
loadBalancer:
servers:
- url: http://127.0.0.1:8000
admin:
loadBalancer:
servers:
- url: http://127.0.0.1:9000
```
```toml tab="Structured (TOML)"
[http.routers.app]
rule = "Host(`example-a.com`)"
service = "app"
[http.routers.admin]
rule = "Host(`example-b.com`)"
service = "admin"
[http.services.app.loadBalancer]
[[http.services.app.loadBalancer.servers]]
url = "http://127.0.0.1:8000"
[http.services.admin.loadBalancer]
[[http.services.admin.loadBalancer.servers]]
url = "http://127.0.0.1:9000"
```
??? example "Declaring and Referencing Middlewares"
Middlewares declared by the file provider can be used by routers from the file provider or by routers from other providers.
When another provider references them, use the `@file` provider suffix.
```yaml tab="Structured (YAML)"
http:
routers:
app:
rule: Host(`secure.example.com`)
entryPoints:
- websecure
middlewares:
- secure-headers
service: app
tls:
options: modern
middlewares:
secure-headers:
headers:
stsSeconds: 31536000
forceSTSHeader: true
services:
app:
loadBalancer:
servers:
- url: http://127.0.0.1:8080
tls:
options:
modern:
minVersion: VersionTLS12
sniStrict: true
```
```toml tab="Structured (TOML)"
[http.routers.app]
rule = "Host(`secure.example.com`)"
entryPoints = ["websecure"]
middlewares = ["secure-headers"]
service = "app"
[http.routers.app.tls]
options = "modern"
[http.middlewares.secure-headers.headers]
stsSeconds = 31536000
forceSTSHeader = true
[http.services.app.loadBalancer]
[[http.services.app.loadBalancer.servers]]
url = "http://127.0.0.1:8080"
[tls.options.modern]
minVersion = "VersionTLS12"
sniStrict = true
```
??? example "Loading Multiple Dynamic Configuration Files"
Configure the file provider with a directory when you want to split dynamic configuration across multiple files.
```yaml tab="Structured (YAML)"
providers:
file:
directory: /etc/traefik/dynamic
watch: true
```
```toml tab="Structured (TOML)"
[providers.file]
directory = "/etc/traefik/dynamic"
watch = true
```
```bash tab="CLI"
--providers.file.directory=/etc/traefik/dynamic
--providers.file.watch=true
```
Example `/etc/traefik/dynamic/http.yml`:
```yaml
http:
routers:
app:
rule: Host(`example.com`)
service: app
services:
app:
loadBalancer:
servers:
- url: http://127.0.0.1:8080
```
Example `/etc/traefik/dynamic/tls.yml`:
```yaml
tls:
certificates:
- certFile: /certs/example.crt
keyFile: /certs/example.key
```
Configuration Options
General
The file provider does not discover services automatically. Define every router, service, middleware, and TLS resource explicitly in the routing configuration file.
When another provider references a resource declared by the file provider, append the @file provider suffix.
For example, a Docker label can reference a file-provider middleware with secure-headers@file.
The examples below use YAML-style field paths.
In TOML, use the equivalent table and array syntax, such as [http.routers.<router_name>] and [[http.services.<service_name>.loadBalancer.servers]].
HTTP
Routers
Define HTTP routers under http.routers.<router_name>.
!!! warning "The character @ is not authorized in the router name <router_name>."
Services
Define HTTP services under http.services.<service_name>.
!!! warning "The character @ is not authorized in the service name <service_name>."
Middlewares
Define HTTP middlewares under http.middlewares.<middleware_name>.
For example, to declare an AddPrefix middleware named add-api, set http.middlewares.add-api.addPrefix.prefix=/api.
More information about available middlewares can be found in the dedicated middlewares section.
!!! warning "The character @ is not authorized in the middleware name <middleware_name>."
!!! warning "Conflicts in Declaration"
If you declare multiple middlewares with the same name but different parameters, the middleware fails to be declared.
| Field | Description | Value |
|---|---|---|
http.middlewares.<middleware_name>.<middleware_type>.<middleware_option> |
With middleware_type the middleware type, such as addPrefix or headers, and middleware_option the option to set. |
prefix: /api |
ServersTransports
Define HTTP ServersTransports under http.serversTransports.<servers_transport_name>.
| Field | Description | Value |
|---|---|---|
http.serversTransports.<servers_transport_name>.* |
See ServersTransport for more information. | serverName: example.org |
TCP
You can declare TCP routers, services, middlewares, and ServersTransports with the file provider.
TCP Routers
Define TCP routers under tcp.routers.<router_name>.
!!! warning "The character @ is not authorized in the router name <router_name>."
| Field | Description | Value |
|---|---|---|
tcp.routers.<router_name>.entryPoints[n] |
See entry points for more information. | websecure |
tcp.routers.<router_name>.rule |
See rule for more information. | HostSNI(`example.com`) |
tcp.routers.<router_name>.ruleSyntax |
Configures the rule syntax to use for parsing the rule on a per-router basis. RuleSyntax is deprecated and will be removed in the next major version. |
v3 |
tcp.routers.<router_name>.middlewares[n] |
See TCP middlewares overview for more information. | ip-allowlist |
tcp.routers.<router_name>.service |
See service for more information. | tcp-app |
tcp.routers.<router_name>.tls |
See TLS for more information. | {} |
tcp.routers.<router_name>.tls.certResolver |
See certResolver for more information. | myresolver |
tcp.routers.<router_name>.tls.domains[n].main |
See TLS for more information. | example.org |
tcp.routers.<router_name>.tls.domains[n].sans[n] |
See TLS for more information. | www.example.org |
tcp.routers.<router_name>.tls.options |
See TLS for more information. | modern |
tcp.routers.<router_name>.tls.passthrough |
See Passthrough for more information. | true |
tcp.routers.<router_name>.priority |
See priority for more information. | 42 |
TCP Services
Define TCP services under tcp.services.<service_name>.
!!! warning "The character @ is not authorized in the service name <service_name>."
TCP Middlewares
Define TCP middlewares under tcp.middlewares.<middleware_name>.
For example, to declare an InFlightConn middleware named limit, set tcp.middlewares.limit.inFlightConn.amount=10.
More information about available middlewares is available in the dedicated TCP middlewares section.
!!! warning "The character @ is not authorized in the middleware name <middleware_name>."
!!! warning "Conflicts in Declaration"
If you declare multiple middlewares with the same name but different parameters, the middleware fails to be declared.
| Field | Description | Value |
|---|---|---|
tcp.middlewares.<middleware_name>.<middleware_type>.<middleware_option> |
With middleware_type the middleware type, such as inFlightConn, and middleware_option the option to set. |
amount: 10 |
TCP ServersTransports
Define TCP ServersTransports under tcp.serversTransports.<servers_transport_name>.
| Field | Description | Value |
|---|---|---|
tcp.serversTransports.<servers_transport_name>.* |
See TCP ServersTransport for more information. | dialTimeout: 30s |
UDP
You can declare UDP routers and services with the file provider.
UDP Routers
Define UDP routers under udp.routers.<router_name>.
!!! warning "The character @ is not authorized in the router name <router_name>."
| Field | Description | Value |
|---|---|---|
udp.routers.<router_name>.entryPoints[n] |
See UDP router entrypoints for more information. | dns |
udp.routers.<router_name>.service |
See UDP router configuration for more information. | dns-service |
UDP Services
Define UDP services under udp.services.<service_name>.
!!! warning "The character @ is not authorized in the service name <service_name>."
| Field | Description | Value |
|---|---|---|
udp.services.<service_name>.loadBalancer.servers[n].address |
See UDP service for more information. | 127.0.0.1:5353 |
udp.services.<service_name>.weighted.services[n].name |
See UDP service for more information. | dns-v1 |
udp.services.<service_name>.weighted.services[n].weight |
See UDP service for more information. | 3 |
TLS
You can declare TLS certificates, options, and stores with the file provider.
Certificates
| Field | Description | Value |
|---|---|---|
tls.certificates[n].certFile |
See TLS certificates for more information. | /certs/example.crt |
tls.certificates[n].keyFile |
See TLS certificates for more information. | /certs/example.key |
tls.certificates[n].stores[n] |
See certificate stores for more information. | default |
TLS Options
TLS Stores
| Field | Description | Value |
|---|---|---|
tls.stores.<store_name>.defaultCertificate.certFile |
See default certificate for more information. | /certs/default.crt |
tls.stores.<store_name>.defaultCertificate.keyFile |
See default certificate for more information. | /certs/default.key |
tls.stores.<store_name>.defaultGeneratedCert.resolver |
See ACME default certificate for more information. | myresolver |
tls.stores.<store_name>.defaultGeneratedCert.domain.main |
See ACME default certificate for more information. | example.org |
tls.stores.<store_name>.defaultGeneratedCert.domain.sans[n] |
See ACME default certificate for more information. | www.example.org |
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 sections of configuration files. These sections must be a valid Go template, and can use sprig template functions.
To illustrate, it is possible to easily define multiple routers, services, and TLS certificates as described in the following examples:
??? example "Configuring Using Templating"
```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"
stores:
- "my-store-foo-{{ $e }}"
- "my-store-bar-{{ $e }}"
{{end}}
```
```toml tab="TOML"
# template-rules.toml
[http]
[http.routers]
{{ range $i, $e := until 100 }}
[http.routers.router{{ $e }}-{{ env "MY_ENV_VAR" }}]
# ...
{{ end }}
[http.services]
{{ range $i, $e := until 100 }}
[http.services.service{{ $e }}]
# ...
{{ end }}
[tcp]
[tcp.routers]
{{ range $i, $e := until 100 }}
[tcp.routers.router{{ $e }}]
# ...
{{ end }}
[tcp.services]
{{ range $i, $e := until 100 }}
[tcp.services.service{{ $e }}]
# ...
{{ 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.options]
{{ range $i, $e := until 10 }}
[tls.options.TLS{{ $e }}]
# ...
{{ end }}
```