homelab/traefik
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Use the same case everywhere

Browse source
This commit is contained in:
Ludovic Fernandez 2019-07-01 11:30:05 +02:00 • committed by Traefiker Bot
parent f6436663eb
commit c7d336f958
179 changed files with 5118 additions and 4436 deletions
Download patch file Download diff file Expand all files Collapse all files

177
docs/content/routing/entrypoints.md
View file

@ -3,7 +3,7 @@
Opening Connections for Incoming Requests
{: .subtitle }
![EntryPoints](../assets/img/entrypoints.png)
![entryPoints](../assets/img/entrypoints.png)
EntryPoints are the network entry points into Traefik.
They define the port which will receive the requests (whether HTTP or TCP).
@ -12,17 +12,27 @@ They define the port which will receive the requests (whether HTTP or TCP).
??? example "Port 80 only"
```toml
```toml tab="File (TOML)"
[entryPoints]
[entryPoints.web]
address = ":80"
address = ":80"
```
```yaml tab="File (YAML)"
entryPoints:
web:
address: ":80"
```
```ini tab="CLI"
--entryPoints.web.address=:80
```
We define an `entrypoint` called `web` that will listen on port `80`.
??? example "Port 80 & 443"
```toml
```toml tab="File (TOML)"
[entryPoints]
[entryPoints.web]
address = ":80"
@ -30,6 +40,20 @@ They define the port which will receive the requests (whether HTTP or TCP).
[entryPoints.web-secure]
address = ":443"
```
```yaml tab="File (YAML)"
entryPoints:
web:
address: ":80"
web-secure:
address: ":443"
```
```ini tab="CLI"
--entryPoints.web.address=:80
--entryPoints.web-secure.address=:443
```
- Two entrypoints are defined: one called `web`, and the other called `web-secure`.
- `web` listens on port `80`, and `web-secure` on port `443`.
@ -43,38 +67,63 @@ You can define them using a toml file, CLI arguments, or a key-value store.
See the complete reference for the list of available options:
```toml tab="File"
```toml tab="File (TOML)"
[entryPoints]
[entryPoints.EntryPoint0]
Address = ":8888"
[entryPoints.EntryPoint0.Transport]
[entryPoints.EntryPoint0.Transport.LifeCycle]
RequestAcceptGraceTimeout = 42
GraceTimeOut = 42
[entryPoints.EntryPoint0.Transport.RespondingTimeouts]
ReadTimeout = 42
WriteTimeout = 42
IdleTimeout = 42
[entryPoints.EntryPoint0.ProxyProtocol]
Insecure = true
TrustedIPs = ["foobar", "foobar"]
[entryPoints.EntryPoint0.ForwardedHeaders]
Insecure = true
TrustedIPs = ["foobar", "foobar"]
address = ":8888"
[entryPoints.EntryPoint0.transport]
[entryPoints.EntryPoint0.transport.lifeCycle]
requestAcceptGraceTimeout = 42
graceTimeOut = 42
[entryPoints.EntryPoint0.transport.respondingTimeouts]
readTimeout = 42
writeTimeout = 42
idleTimeout = 42
[entryPoints.EntryPoint0.proxyProtocol]
insecure = true
trustedIPs = ["foobar", "foobar"]
[entryPoints.EntryPoint0.forwardedHeaders]
insecure = true
trustedIPs = ["foobar", "foobar"]
```
```yaml tab="File (YAML)"
entryPoints:
EntryPoint0:
address: ":8888"
transport:
lifeCycle:
requestAcceptGraceTimeout: 42
graceTimeOut: 42
respondingTimeouts:
readTimeout: 42
writeTimeout: 42
idleTimeout: 42
proxyProtocol:
insecure: true
trustedIPs:
- "foobar"
- "foobar"
forwardedHeaders:
insecure: true
trustedIPs:
- "foobar"
- "foobar"
```
```ini tab="CLI"
--entryPoints.EntryPoint0.Address=:8888
--entryPoints.EntryPoint0.Transport.LifeCycle.RequestAcceptGraceTimeout=42
--entryPoints.EntryPoint0.Transport.LifeCycle.GraceTimeOut=42
--entryPoints.EntryPoint0.Transport.RespondingTimeouts.ReadTimeout=42
--entryPoints.EntryPoint0.Transport.RespondingTimeouts.WriteTimeout=42
--entryPoints.EntryPoint0.Transport.RespondingTimeouts.IdleTimeout=42
--entryPoints.EntryPoint0.ProxyProtocol.Insecure=true
--entryPoints.EntryPoint0.ProxyProtocol.TrustedIPs=foobar,foobar
--entryPoints.EntryPoint0.ForwardedHeaders.Insecure=true
--entryPoints.EntryPoint0.ForwardedHeaders.TrustedIPs=foobar,foobar
--entryPoints.EntryPoint0.address=:8888
--entryPoints.EntryPoint0.transport.lifeCycle.requestAcceptGraceTimeout=42
--entryPoints.EntryPoint0.transport.lifeCycle.graceTimeOut=42
--entryPoints.EntryPoint0.transport.respondingTimeouts.readTimeout=42
--entryPoints.EntryPoint0.transport.respondingTimeouts.writeTimeout=42
--entryPoints.EntryPoint0.transport.respondingTimeouts.idleTimeout=42
--entryPoints.EntryPoint0.proxyProtocol.insecure=true
--entryPoints.EntryPoint0.proxyProtocol.trustedIPs=foobar,foobar
--entryPoints.EntryPoint0.forwardedHeaders.insecure=true
--entryPoints.EntryPoint0.forwardedHeaders.trustedIPs=foobar,foobar
```
## ProxyProtocol
@ -83,7 +132,7 @@ Traefik supports [ProxyProtocol](https://www.haproxy.org/download/1.8/doc/proxy-
??? example "Enabling Proxy Protocol with Trusted IPs"
```toml
```toml tab="File (TOML)"
[entryPoints]
[entryPoints.web]
address = ":80"
@ -92,6 +141,21 @@ Traefik supports [ProxyProtocol](https://www.haproxy.org/download/1.8/doc/proxy-
trustedIPs = ["127.0.0.1/32", "192.168.1.7"]
```
```yaml tab="File (YAML)"
entryPoints:
web:
address: ":80"
proxyProtocol
trustedIPs:
- "127.0.0.1/32"
- "192.168.1.7"
```
```ini tab="CLI"
--entryPoints.web.address=:80
--entryPoints.web.proxyProtocol.trustedIPs=127.0.0.1/32,192.168.1.7
```
IPs in `trustedIPs` only will lead to remote client address replacement: Declare load-balancer IPs or CIDR range here.
??? example "Insecure Mode -- Testing Environment Only"
@ -99,7 +163,7 @@ Traefik supports [ProxyProtocol](https://www.haproxy.org/download/1.8/doc/proxy-
In a test environments, you can configure Traefik to trust every incoming connection.
Doing so, every remote client address will be replaced (`trustedIPs` won't have any effect)
```toml
```toml tab="File (TOML)"
[entryPoints]
[entryPoints.web]
address = ":80"
@ -107,7 +171,20 @@ Traefik supports [ProxyProtocol](https://www.haproxy.org/download/1.8/doc/proxy-
[entryPoints.web.proxyProtocol]
insecure = true
```
```yaml tab="File (YAML)"
entryPoints:
web:
address: ":80"
proxyProtocol:
insecure: true
```
```ini tab="CLI"
--entryPoints.web.address=:80
--entryPoints.web.proxyProtocol.insecure
```
!!! warning "Queuing Traefik behind Another Load Balancer"
When queuing Traefik behind another load-balancer, make sure to configure Proxy Protocol on both sides.
@ -119,7 +196,7 @@ You can configure Traefik to trust the forwarded headers information (`X-Forward
??? example "Trusting Forwarded Headers from specific IPs"
```toml
```toml tab="File (TOML)"
[entryPoints]
[entryPoints.web]
address = ":80"
@ -128,13 +205,41 @@ You can configure Traefik to trust the forwarded headers information (`X-Forward
trustedIPs = ["127.0.0.1/32", "192.168.1.7"]
```
```yaml tab="File (YAML)"
entryPoints:
web:
address: ":80"
forwardedHeaders
trustedIPs:
- "127.0.0.1/32"
- "192.168.1.7"
```
```ini tab="CLI"
--entryPoints.web.address=:80
--entryPoints.web.forwardedHeaders.trustedIPs=127.0.0.1/32,192.168.1.7
```
??? example "Insecure Mode -- Always Trusting Forwarded Headers"
```toml
```toml tab="File (TOML)"
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.web.forwardedHeaders]
insecure = true
insecure = true
```
```yaml tab="File (YAML)"
entryPoints:
web:
address: ":80"
forwardedHeaders:
insecure: true
```
```ini tab="CLI"
--entryPoints.web.address=:80
--entryPoints.web.forwardedHeaders.insecure
```

88
docs/content/routing/overview.md
View file

@ -38,10 +38,11 @@ Static configuration:
```
```yaml tab="YAML"
entrypoints:
entryPoints:
web:
# Listen on port 8081 for incoming requests
address: :8081
providers:
# Enable the file provider to define routers / middlewares / services in a file
file: {}
@ -63,13 +64,13 @@ Dynamic configuration:
[http.middlewares]
# Define an authentication mechanism
[http.middlewares.test-user.basicauth]
[http.middlewares.test-user.basicAuth]
users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"]
[http.services]
# Define how to reach an existing service on our infrastructure
[http.services.whoami.loadbalancer]
[[http.services.whoami.loadbalancer.servers]]
[http.services.whoami.loadBalancer]
[[http.services.whoami.loadBalancer.servers]]
url = "http://private/whoami-service"
```
@ -85,16 +86,18 @@ http:
- test-user
# If the rule matches, forward to the whoami service (declared below)
service: whoami
middlewares:
# Define an authentication mechanism
test-user:
basicAuth:
users:
- test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
services:
# Define how to reach an existing service on our infrastructure
whoami:
loadbalancer:
loadBalancer:
servers:
- url: http://private/whoami-service
```
@ -115,17 +118,17 @@ http:
```toml tab="TOML"
[entryPoints]
[entryPoints.web]
# Listen on port 8081 for incoming requests
address = ":8081"
[entryPoints.web]
# Listen on port 8081 for incoming requests
address = ":8081"
[providers]
# Enable the file provider to define routers / middlewares / services in a file
[providers.file]
# Enable the file provider to define routers / middlewares / services in a file
[providers.file]
```
```yaml tab="YAML"
entrypoints:
entryPoints:
web:
# Listen on port 8081 for incoming requests
address: :8081
@ -139,42 +142,43 @@ http:
```toml tab="TOML"
# http routing section
[http]
[http.routers]
# Define a connection between requests and services
[http.routers.to-whoami]
rule = "Host(`domain`) && PathPrefix(`/whoami/`)"
# If the rule matches, applies the middleware
middlewares = ["test-user"]
# If the rule matches, forward to the whoami service (declared below)
service = "whoami"
[http.routers]
# Define a connection between requests and services
[http.routers.to-whoami]
rule = "Host(`domain`) && PathPrefix(`/whoami/`)"
# If the rule matches, applies the middleware
middlewares = ["test-user"]
# If the rule matches, forward to the whoami service (declared below)
service = "whoami"
[http.middlewares]
# Define an authentication mechanism
[http.middlewares.test-user.basicauth]
users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"]
[http.middlewares]
# Define an authentication mechanism
[http.middlewares.test-user.basicAuth]
users = ["test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/"]
[http.services]
# Define how to reach an existing service on our infrastructure
[http.services.whoami.loadbalancer]
[[http.services.whoami.loadbalancer.servers]]
url = "http://private/whoami-service"
[http.services]
# Define how to reach an existing service on our infrastructure
[http.services.whoami.loadBalancer]
[[http.services.whoami.loadBalancer.servers]]
url = "http://private/whoami-service"
[tcp]
[tcp.routers]
[tcp.routers.to-whoami-tcp]
rule = "HostSNI(`whoami-tcp.traefik.io`)"
service = "whoami-tcp"
[tcp.routers.to-whoami-tcp.tls]
[tcp]
[tcp.routers]
[tcp.routers.to-whoami-tcp]
rule = "HostSNI(`whoami-tcp.traefik.io`)"
service = "whoami-tcp"
[tcp.routers.to-whoami-tcp.tls]
[tcp.services]
[tcp.services.whoami-tcp.loadbalancer]
[[tcp.services.whoami-tcp.loadbalancer.servers]]
address = "xx.xx.xx.xx:xx"
[tcp.services]
[tcp.services.whoami-tcp.loadBalancer]
[[tcp.services.whoami-tcp.loadBalancer.servers]]
address = "xx.xx.xx.xx:xx"
```
```yaml tab="YAML"
# http routing section
http:
routers:
# Define a connection between requests and services
to-whoami:
@ -184,26 +188,30 @@ http:
- test-user
# If the rule matches, forward to the whoami service (declared below)
service: whoami
middlewares:
# Define an authentication mechanism
test-user:
basicAuth:
users:
- test:$apr1$H6uskkkW$IgXLP6ewTrSuBkTrqE8wj/
services:
# Define how to reach an existing service on our infrastructure
whoami:
loadbalancer:
loadBalancer:
servers:
- url: http://private/whoami-service
tcp:
routers:
to-whoami-tcp:
service: whoami-tcp
rule: HostSNI(`whoami-tcp.traefik.io`)
services:
whoami-tcp:
loadbalancer:
loadBalancer:
servers:
- address: xx.xx.xx.xx:xx
```

488
docs/content/routing/routers/index.md
View file

@ -12,40 +12,84 @@ In the process, routers may use pieces of [middleware](../../middlewares/overvie
??? example "Requests /foo are Handled by service-foo -- Using the [File Provider](../../providers/file.md)"
```toml
```toml tab="TOML"
[http.routers]
[http.routers.my-router]
rule = "Path(`/foo`)"
service = "service-foo"
rule = "Path(`/foo`)"
service = "service-foo"
```
```yaml tab="YAML"
http:
routers:
my-router:
rule: "Path(`/foo`)"
service: service-foo
```
??? example "With a [middleware](../../middlewares/overview.md) -- using the [File Provider](../../providers/file.md)"
```toml
```toml tab="TOML"
[http.routers]
[http.routers.my-router]
rule = "Path(`/foo`)"
middlewares = ["authentication"] # declared elsewhere
service = "service-foo"
rule = "Path(`/foo`)"
# declared elsewhere
middlewares = ["authentication"]
service = "service-foo"
```
```yaml tab="YAML"
http:
routers:
my-router:
rule: "Path(`/foo`)"
# declared elsewhere
middlewares:
- authentication
service: service-foo
```
??? example "Forwarding all (non-tls) requests on port 3306 to a database service"
```toml
[entryPoints]
[entryPoints.mysql-default]
address = ":80"
[entryPoints.mysql-default]
address = ":3306"
```toml tab="TOML"
## Static configuration ##
[entryPoints]
[entryPoints.web]
address = ":80"
[entryPoints.mysql-default]
address = ":3306"
## Dynamic configuration ##
[tcp]
[tcp.routers]
[tcp.routers.to-database]
entryPoints = ["mysql-default"]
# Catch every request (only available rule for non-tls routers. See below.)
rule = "HostSNI(`*`)"
service = "database"
```
```toml
[tcp]
[tcp.routers]
[tcp.routers.to-database]
entryPoints = ["mysql-default"]
rule = "HostSNI(`*`)" # Catch every request (only available rule for non-tls routers. See below.)
service = "database"
```yaml tab="YAML"
## Static configuration ##
entryPoints:
web:
address: ":80"
mysql-default:
address: ":3306"
## Dynamic configuration ##
tcp:
routers:
to-database:
entryPoints:
- "mysql-default"
# Catch every request (only available rule for non-tls routers. See below.)
rule: "HostSNI(`*`)"
service: database
```
## Configuring HTTP Routers
@ -56,43 +100,94 @@ If not specified, HTTP routers will accept requests from all defined entry point
If you want to limit the router scope to a set of entry points, set the `entryPoints` option.
??? example "Listens to Every EntryPoint"
```toml
```toml tab="TOML"
## Static configuration ##
[entryPoints]
[entryPoints.web]
# ...
[entryPoints.web-secure]
# ...
[entryPoints.other]
# ...
[entryPoints.web]
# ...
[entryPoints.web-secure]
# ...
[entryPoints.other]
# ...
## Dynamic configuration ##
[http.routers]
[http.routers.Router-1]
# By default, routers listen to every entry points
rule = "Host(`traefik.io`)"
service = "service-1"
```
```toml
[http.routers]
[http.routers.Router-1]
# By default, routers listen to every entrypoints
rule = "Host(`traefik.io`)"
service = "service-1"
```yaml tab="YAML"
## Static configuration ##
entryPoints:
web:
# ...
web-secure:
# ...
other:
# ...
## Dynamic configuration ##
http:
routers:
Router-1:
# By default, routers listen to every entry points
rule: "Host(`traefik.io`)"
service: "service-1"
```
??? example "Listens to Specific EntryPoints"
```toml
```toml tab="TOML"
## Static configuration ##
[entryPoints]
[entryPoints.web]
# ...
[entryPoints.web-secure]
# ...
[entryPoints.other]
# ...
[entryPoints.web]
# ...
[entryPoints.web-secure]
# ...
[entryPoints.other]
# ...
## Dynamic configuration ##
[http.routers]
[http.routers.Router-1]
# won't listen to entry point web
entryPoints = ["web-secure", "other"]
rule = "Host(`traefik.io`)"
service = "service-1"
```
```toml
[http.routers]
[http.routers.Router-1]
entryPoints = ["web-secure", "other"] # won't listen to entrypoint web
rule = "Host(`traefik.io`)"
service = "service-1"
```yaml tab="YAML"
## Static configuration ##
entryPoints:
web:
# ...
web-secure:
# ...
other:
# ...
## Dynamic configuration ##
http:
routers:
Router-1:
# won't listen to entry point web
entryPoints:
- "web-secure"
- "other"
rule: "Host(`traefik.io`)"
service: "service-1"
```
### Rule
@ -170,12 +265,23 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted
??? example "Configuring the router to accept HTTPS requests only"
```toml
```toml tab="TOML"
[http.routers]
[http.routers.Router-1]
rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
service = "service-id"
[http.routers.Router-1.tls] # will terminate the TLS request
[http.routers.Router-1]
rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
service = "service-id"
# will terminate the TLS request
[http.routers.Router-1.tls]
```
```yaml tab="YAML"
http:
routers:
Router-1:
rule: "Host(`foo-domain`) && Path(`/foo-path/`)"
service: service-id
# will terminate the TLS request
tls: {}
```
!!! note "HTTPS & ACME"
@ -192,16 +298,31 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted
??? example "HTTP & HTTPS routes"
```toml
```toml tab="TOML"
[http.routers]
[http.routers.my-https-router]
rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
service = "service-id"
[http.routers.my-https-router.tls] # will terminate the TLS request
[http.routers.my-https-router]
rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
service = "service-id"
# will terminate the TLS request
[http.routers.my-https-router.tls]
[http.routers.my-http-router]
rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
service = "service-id"
[http.routers.my-http-router]
rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
service = "service-id"
```
```yaml tab="YAML"
http:
routers:
my-https-router:
rule: "Host(`foo-domain`) && Path(`/foo-path/`)"
service: service-id
# will terminate the TLS request
tls: {}
my-http-router:
rule: "Host(`foo-domain`) && Path(`/foo-path/`)"
service: service-id
```
#### `Options`
@ -209,23 +330,43 @@ Traefik will terminate the SSL connections (meaning that it will send decrypted
The `Options` field enables fine-grained control of the TLS parameters.
It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied only if a `Host` rule is defined.
??? example "Configuring the tls options"
??? example "Configuring the TLS options"
```toml
```toml tab="TOML"
[http.routers]
[http.routers.Router-1]
rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
service = "service-id"
[http.routers.Router-1.tls] # will terminate the TLS request
options = "foo"
[http.routers.Router-1]
rule = "Host(`foo-domain`) && Path(`/foo-path/`)"
service = "service-id"
# will terminate the TLS request
[http.routers.Router-1.tls]
options = "foo"
[tls.options]
[tls.options.foo]
minVersion = "VersionTLS12"
cipherSuites = [
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
"TLS_RSA_WITH_AES_256_GCM_SHA384"
]
minVersion = "VersionTLS12"
cipherSuites = [
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
"TLS_RSA_WITH_AES_256_GCM_SHA384"
]
```
```yaml tab="YAML"
http:
routers:
Router-1:
rule: "Host(`foo-domain`) && Path(`/foo-path/`)"
service: service-id
# will terminate the TLS request
tls:
options: foo
tls:
options:
foo:
minVersion: VersionTLS12
cipherSuites:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
```
## Configuring TCP Routers
@ -242,44 +383,100 @@ If you want to limit the router scope to a set of entry points, set the entry po
??? example "Listens to Every Entry Point"
```toml
```toml tab="TOML"
## Static configuration ##
[entryPoints]
[entryPoints.web]
# ...
[entryPoints.web-secure]
# ...
[entryPoints.other]
# ...
[entryPoints.web]
# ...
[entryPoints.web-secure]
# ...
[entryPoints.other]
# ...
## Dynamic configuration ##
[tcp.routers]
[tcp.routers.Router-1]
# By default, routers listen to every entrypoints
rule = "HostSNI(`traefik.io`)"
service = "service-1"
# will route TLS requests (and ignore non tls requests)
[tcp.routers.Router-1.tls]
```
```toml
[tcp.routers]
[tcp.routers.Router-1]
```yaml tab="YAML"
## Static configuration ##
entryPoints:
web:
# ...
web-secure:
# ...
other:
# ...
## Dynamic configuration ##
tcp:
routers:
Router-1:
# By default, routers listen to every entrypoints
rule = "HostSNI(`traefik.io`)"
service = "service-1"
[tcp.routers.Router-1.tls] # will route TLS requests (and ignore non tls requests)
rule: "HostSNI(`traefik.io`)"
service: "service-1"
# will route TLS requests (and ignore non tls requests)
tls: {}
```
??? example "Listens to Specific Entry Points"
```toml
```toml tab="TOML"
## Static configuration ##
[entryPoints]
[entryPoints.web]
# ...
[entryPoints.web-secure]
# ...
[entryPoints.other]
# ...
```
```toml
[entryPoints.web]
# ...
[entryPoints.web-secure]
# ...
[entryPoints.other]
# ...
## Dynamic configuration ##
[tcp.routers]
[tcp.routers.Router-1]
entryPoints = ["web-secure", "other"] # won't listen to entrypoint web
rule = "HostSNI(`traefik.io`)"
service = "service-1"
[tcp.routers.Router-1.tls] # will route TLS requests (and ignore non tls requests)
[tcp.routers.Router-1]
# won't listen to entry point web
entryPoints = ["web-secure", "other"]
rule = "HostSNI(`traefik.io`)"
service = "service-1"
# will route TLS requests (and ignore non tls requests)
[tcp.routers.Router-1.tls]
```
```yaml tab="YAML"
## Static configuration ##
entryPoints:
web:
# ...
web-secure:
# ...
other:
# ...
## Dynamic configuration ##
tcp:
routers:
Router-1:
# won't listen to entry point web
entryPoints:
- "web-secure"
- "other"
rule: "HostSNI(`traefik.io`)"
service: "service-1"
# will route TLS requests (and ignore non tls requests)
tls: {}
```
### Rule
@ -312,23 +509,44 @@ Services are the target for the router.
??? example "Configuring TLS Termination"
```toml
```toml tab="TOML"
[tcp.routers]
[tcp.routers.Router-1]
rule = "HostSNI(`foo-domain`)"
service = "service-id"
[tcp.routers.Router-1.tls] # will terminate the TLS request by default
[tcp.routers.Router-1]
rule = "HostSNI(`foo-domain`)"
service = "service-id"
# will terminate the TLS request by default
[tcp.routers.Router-1.tls]
```
```yaml tab="YAML"
tcp:
routers:
Router-1:
rule: "HostSNI(`foo-domain`)"
service: service-id
# will terminate the TLS request by default
tld: {}
```
??? example "Configuring passthrough"
```toml
```toml tab="TOML"
[tcp.routers]
[tcp.routers.Router-1]
rule = "HostSNI(`foo-domain`)"
service = "service-id"
[tcp.routers.Router-1.tls]
passthrough=true
[tcp.routers.Router-1]
rule = "HostSNI(`foo-domain`)"
service = "service-id"
[tcp.routers.Router-1.tls]
passthrough = true
```
```yaml tab="YAML"
tcp:
routers:
Router-1:
rule: "HostSNI(`foo-domain`)"
service: service-id
tls:
passthrough: true
```
!!! note "TLS & ACME"
@ -342,19 +560,39 @@ It refers to a [TLS Options](../../https/tls.md#tls-options) and will be applied
??? example "Configuring the tls options"
```toml
```toml tab="TOML"
[tcp.routers]
[tcp.routers.Router-1]
rule = "HostSNI(`foo-domain`)"
service = "service-id"
[tcp.routers.Router-1.tls] # will terminate the TLS request
options = "foo"
[tcp.routers.Router-1]
rule = "HostSNI(`foo-domain`)"
service = "service-id"
# will terminate the TLS request
[tcp.routers.Router-1.tls]
options = "foo"
[tls.options]
[tls.options.foo]
minVersion = "VersionTLS12"
cipherSuites = [
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
"TLS_RSA_WITH_AES_256_GCM_SHA384"
]
minVersion = "VersionTLS12"
cipherSuites = [
"TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
"TLS_RSA_WITH_AES_256_GCM_SHA384"
]
```
```yaml tab="YAML"
tcp:
routers:
Router-1:
rule: "HostSNI(`foo-domain`)"
service: service-id
# will terminate the TLS request
tls:
options: foo
tls:
options:
foo:
minVersion: VersionTLS12
cipherSuites:
- "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256"
- "TLS_RSA_WITH_AES_256_GCM_SHA384"
```

310
docs/content/routing/services/index.md
View file

@ -11,25 +11,45 @@ The `Services` are responsible for configuring how to reach the actual services
??? example "Declaring an HTTP Service with Two Servers -- Using the [File Provider](../../providers/file.md)"
```toml
```toml tab="TOML"
[http.services]
[http.services.my-service.LoadBalancer]
[[http.services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
[[http.services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-2/"
[http.services.my-service.loadBalancer]
[[http.services.my-service.loadBalancer.servers]]
url = "http://private-ip-server-1/"
[[http.services.my-service.loadBalancer.servers]]
url = "http://private-ip-server-2/"
```
```yaml tab="YAML"
http:
services:
my-service:
loadBalancer:
servers:
- url: "http://private-ip-server-1/"
- url: "http://private-ip-server-2/"
```
??? example "Declaring a TCP Service with Two Servers -- Using the [File Provider](../../providers/file.md)"
```toml
```toml tab="TOML"
[tcp.services]
[tcp.services.my-service.LoadBalancer]
[[tcp.services.my-service.LoadBalancer.servers]]
address = "xx.xx.xx.xx:xx"
[[tcp.services.my-service.LoadBalancer.servers]]
address = "xx.xx.xx.xx:xx"
[tcp.services.my-service.loadBalancer]
[[tcp.services.my-service.loadBalancer.servers]]
address = "xx.xx.xx.xx:xx"
[[tcp.services.my-service.loadBalancer.servers]]
address = "xx.xx.xx.xx:xx"
```
```yaml tab="YAML"
tcp:
services:
my-service:
loadBalancer:
servers:
- address: "xx.xx.xx.xx:xx"
- address: "xx.xx.xx.xx:xx"
```
## Configuring HTTP Services
@ -46,14 +66,24 @@ The load balancers are able to load balance the requests between multiple instan
??? example "Declaring a Service with Two Servers (with Load Balancing) -- Using the [File Provider](../../providers/file.md)"
```toml
```toml tab="TOML"
[http.services]
[http.services.my-service.LoadBalancer]
[[http.services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
[[http.services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-2/"
[http.services.my-service.loadBalancer]
[[http.services.my-service.loadBalancer.servers]]
url = "http://private-ip-server-1/"
[[http.services.my-service.loadBalancer.servers]]
url = "http://private-ip-server-2/"
```
```yaml tab="YAML"
http:
services:
my-service:
loadBalancer:
servers:
- url: "http://private-ip-server-1/"
- url: "http://private-ip-server-2/"
```
#### Servers
@ -68,11 +98,20 @@ The `url` option point to a specific instance.
??? example "A Service with One Server -- Using the [File Provider](../../providers/file.md)"
```toml
```toml tab="TOML"
[http.services]
[http.services.my-service.LoadBalancer]
[[http.services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
[http.services.my-service.loadBalancer]
[[http.services.my-service.loadBalancer.servers]]
url = "http://private-ip-server-1/"
```
```yaml tab="YAML"
http:
services:
my-service:
loadBalancer:
servers:
url: "http://private-ip-server-1/"
```
#### Load-balancing
@ -81,13 +120,23 @@ For now, only round robin load balancing is supported:
??? example "Load Balancing -- Using the [File Provider](../../providers/file.md)"
```toml
```toml tab="TOML"
[http.services]
[http.services.my-service.LoadBalancer]
[[http.services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
[[http.services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
[http.services.my-service.loadBalancer]
[[http.services.my-service.loadBalancer.servers]]
url = "http://private-ip-server-1/"
[[http.services.my-service.loadBalancer.servers]]
url = "http://private-ip-server-2/"
```
```yaml tab="YAML"
http:
services:
my-service:
loadBalancer:
servers:
- url: "http://private-ip-server-1/"
- url: "http://private-ip-server-2/"
```
#### Sticky sessions
@ -109,39 +158,56 @@ On subsequent requests, the client is forwarded to the same server.
??? example "Adding Stickiness"
```toml
```toml tab="TOML"
[http.services]
[http.services.my-service]
[http.services.my-service.LoadBalancer.stickiness]
secureCookie = true
httpOnlyCookie = true
[http.services.my-service.loadBalancer.stickiness]
```
```yaml tab="YAML"
http:
services:
my-service:
loadBalancer:
stickiness: {}
```
??? example "Adding Stickiness with a Custom Cookie Name"
```toml
```toml tab="TOML"
[http.services]
[http.services.my-service]
[http.services.my-service.LoadBalancer.stickiness]
cookieName = "my_stickiness_cookie_name"
secureCookie = true
httpOnlyCookie = true
[http.services.my-service.loadBalancer.stickiness]
cookieName = "my_stickiness_cookie_name"
secureCookie = true
httpOnlyCookie = true
```
```yaml tab="YAML"
http:
services:
my-service:
loadBalancer:
stickiness:
cookieName: my_stickiness_cookie_name
secureCookie: true
httpOnlyCookie: true
```
#### Health Check
Configure healthcheck to remove unhealthy servers from the load balancing rotation.
Configure health check to remove unhealthy servers from the load balancing rotation.
Traefik will consider your servers healthy as long as they return status codes between `2XX` and `3XX` to the health check requests (carried out every `interval`).
Below are the available options for the health check mechanism:
- `path` is appended to the server URL to set the healcheck endpoint.
- `scheme`, if defined, will replace the server URL `scheme` for the healthcheck endpoint
- `hostname`, if defined, will replace the server URL `hostname` for the healthcheck endpoint.
- `port`, if defined, will replace the server URL `port` for the healthcheck endpoint.
- `interval` defines the frequency of the healthcheck calls.
- `timeout` defines the maximum duration Traefik will wait for a healthcheck request before considering the server failed (unhealthy).
- `headers` defines custom headers to be sent to the healthcheck endpoint.
- `path` is appended to the server URL to set the health check endpoint.
- `scheme`, if defined, will replace the server URL `scheme` for the health check endpoint
- `hostname`, if defined, will replace the server URL `hostname` for the health check endpoint.
- `port`, if defined, will replace the server URL `port` for the health check endpoint.
- `interval` defines the frequency of the health check calls.
- `timeout` defines the maximum duration Traefik will wait for a health check request before considering the server failed (unhealthy).
- `headers` defines custom headers to be sent to the health check endpoint.
!!! note "Interval & Timeout Format"
@ -153,50 +219,93 @@ Below are the available options for the health check mechanism:
Traefik keeps monitoring the health of unhealthy servers.
If a server has recovered (returning `2xx` -> `3xx` responses again), it will be added back to the load balacer rotation pool.
??? example "Custom Interval & Timeout -- Using the File Provider"
??? example "Custom Interval & Timeout -- Using the [File Provider](../../providers/file.md)"
```toml
```toml tab="TOML"
[http.services]
[http.servicess.Service-1]
[http.services.Service-1.healthcheck]
path = "/health"
interval = "10s"
timeout = "3s"
[http.services.Service-1.loadBalancer.healthCheck]
path = "/health"
interval = "10s"
timeout = "3s"
```
??? example "Custom Port -- Using the File Provider"
```yaml tab="YAML"
http:
servicess:
Service-1:
loadBalancer:
healthCheck:
path: /health
interval: "10s"
timeout: "3s"
```
```toml
??? example "Custom Port -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
[http.services]
[http.services.Service-1]
[http.services.Service-1.healthcheck]
path = "/health"
port = 8080
```
??? example "Custom Scheme -- Using the File Provider"
```toml
[http.services]
[http.services.Service-1]
[http.services.Service-1.healthcheck]
path = "/health"
scheme = "http"
```
??? example "Additional HTTP Headers -- Using the File Provider"
```toml
[http.services]
[http.services.Service-1]
[http.servicess.Service-1.healthcheck]
path = "/health"
[Service.Service-1.healthcheck.headers]
My-Custom-Header = "foo"
My-Header = "bar"
[http.services.Service-1.loadBalancer.healthCheck]
path = "/health"
port = 8080
```
```yaml tab="YAML"
http:
services:
Service-1:
loadBalancer:
healthCheck:
path: /health
port: 8080
```
??? example "Custom Scheme -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
[http.services]
[http.services.Service-1]
[http.services.Service-1.loadBalancer.healthCheck]
path = "/health"
scheme = "http"
```
```yaml tab="YAML"
http:
services:
Service-1:
loadBalancer:
healthCheck:
path: /health
scheme: http
```
??? example "Additional HTTP Headers -- Using the [File Provider](../../providers/file.md)"
```toml tab="TOML"
[http.services]
[http.services.Service-1]
[http.services.Service-1.loadBalancer.healthCheck]
path = "/health"
[http.services.Service-1.loadBalancer.healthCheck.headers]
My-Custom-Header = "foo"
My-Header = "bar"
```
```yaml tab="YAML"
http:
services:
Service-1:
loadBalancer:
healthCheck:
path: /health
headers:
My-Custom-Header: foo
My-Header: bar
```
## Configuring TCP Services
### General
@ -211,13 +320,23 @@ The load balancers are able to load balance the requests between multiple instan
??? example "Declaring a Service with Two Servers -- Using the [File Provider](../../providers/file.md)"
```toml
```toml tab="TOML"
[tcp.services]
[tcp.services.my-service.LoadBalancer]
[[tcp.services.my-service.LoadBalancer.servers]]
address = "xx.xx.xx.xx:xx"
[[tcp.services.my-service.LoadBalancer.servers]]
address = "xx.xx.xx.xx:xx"
[tcp.services.my-service.loadBalancer]
[[tcp.services.my-service.loadBalancer.servers]]
address = "xx.xx.xx.xx:xx"
[[tcp.services.my-service.loadBalancer.servers]]
address = "xx.xx.xx.xx:xx"
```
```yaml tab="YAML"
tcp:
services:
my-service:
loadBalancer:
servers:
- address: "xx.xx.xx.xx:xx"
- address: "xx.xx.xx.xx:xx"
```
#### Servers
@ -227,9 +346,18 @@ The `address` option (IP:Port) point to a specific instance.
??? example "A Service with One Server -- Using the [File Provider](../../providers/file.md)"
```toml
```toml tab="TOML"
[tcp.services]
[tcp.services.my-service.LoadBalancer]
[[tcp.services.my-service.LoadBalancer.servers]]
address = "xx.xx.xx.xx:xx"
[tcp.services.my-service.loadBalancer]
[[tcp.services.my-service.loadBalancer.servers]]
address = "xx.xx.xx.xx:xx"
```
```yaml tab="YAML"
tcp:
services:
my-service:
loadBalancer:
servers:
address: "xx.xx.xx.xx:xx"
```