homelab/traefik
1
0
Fork 0
Code Activity

Documentation Revamp

Browse source 
Co-authored-by: jbdoumenjou <jb.doumenjou@gmail.com>
This commit is contained in:
Gérald Croës 2019-02-26 05:50:07 -08:00 • committed by Traefiker Bot
parent 848e45c22c
commit ac6b11037d
174 changed files with 5858 additions and 4002 deletions
Download patch file Download diff file Expand all files Collapse all files

190
docs/content/routing/services.md Normal file
View file

@ -0,0 +1,190 @@
# Services
Configuring How to Reach the Services
{: .subtitle }
![Services](../assets/img/services.png)
The `Services` are responsible for configuring how to reach the actual services that will eventually handle the incoming requests.
## Configuration Example
??? example "Declaring a Service with Two Servers (with Load Balancing) -- Using the [File Provider](../providers/file.md)"
```toml
[Services]
[Services.my-service.LoadBalancer]
method = "wrr" # Load Balancing based on weights
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
weight = 30 # 30% of the requests will go to that instance
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-2/"
weight = 70 # 70% of the requests will go to that instance
```
## Configuration
### General
Currently, the `LoadBalancer` service is the only supported kind of `Service` (see below).
However, since Traefik is an ever evolving project, other kind of Services will be available in the future,
reason why you have to specify what kind of service you declare.
### Load Balancer
The `LoadBalancer` service is able to load balance the requests between multiple instances of your programs.
??? example "Declaring a Service with Two Servers (with Load Balancing) -- Using the [File Provider](../providers/file.md)"
```toml
[Services]
[Services.my-service.LoadBalancer]
method = "wrr" # Load Balancing based on weights
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
weight = 50 # 50% of the requests will go to that instance
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-2/"
weight = 50 # 50% of the requests will go to that instance
```
#### Servers
Servers declare a single instance of your program.
The `url` option point to a specific instance.
The `weight` option defines the weight of the server for the load balancing algorithm.
!!! note
Paths in the servers' `url` have no effet.
If you want the requests to be sent to a specific path on your servers,
configure your [`routers`](./routers.md) to use a corresponding [Middleware](../middlewares/overview.md) (e.g. the [AddPrefix](../middlewares/addprefix.md) or [ReplacePath](../middlewares/replacepath.md)) middlewares.
??? example "A Service with One Server -- Using the [File Provider](../providers/file.md)"
```toml
[Services]
[Services.my-service.LoadBalancer]
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
```
#### Load-balancing
Various methods of load balancing are supported:
- `wrr`: Weighted Round Robin.
- `drr`: Dynamic Round Robin: increases weights on servers that perform better than others (rolls back to original weights when the server list is updated)
??? example "Load Balancing Using DRR -- Using the [File Provider](../providers/file.md)"
```toml
[Services]
[Services.my-service.LoadBalancer]
method = "drr"
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
[[Services.my-service.LoadBalancer.servers]]
url = "http://private-ip-server-1/"
```
#### Sticky sessions
When sticky sessions are enabled, a cookie is set on the initial request to track which server handles the first response.
On subsequent requests, the client is forwarded to the same server.
!!! note "Stickiness & Unhealthy Servers"
If the server specified in the cookie becomes unhealthy, the request will be forwarded to a new server (and the cookie will keep track of the new server).
!!! note "Cookie Name"
The default cookie name is an abbreviation of a sha1 (ex: `_1d52e`).
??? example "Adding Stickiness"
```toml
[Services]
[Services.my-service]
[Services.my-service.LoadBalancer.stickiness]
```
??? example "Adding Stickiness with a Custom Cookie Name"
```toml
[Services]
[Services.my-service]
[Services.my-service.LoadBalancer.stickiness]
cookieName = "my_stickiness_cookie_name"
```
#### Health Check
Configure healthcheck 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.
!!! note "Interval & Timeout Format"
Interval and timeout are to be given in a format understood by [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration).
The interval must be greater than the timeout. If configuration doesn't reflect this, the interval will be set to timeout + 1 second.
!!! note "Recovering Servers"
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"
```toml
[Services]
[Servicess.Service-1]
[Services.Service-1.healthcheck]
path = "/health"
interval = "10s"
timeout = "3s"
```
??? example "Custom Port -- Using the File Provider"
```toml
[Services]
[Services.Service-1]
[Services.Service-1.healthcheck]
path = "/health"
port = 8080
```
??? example "Custom Scheme -- Using the File Provider"
```toml
[Services]
[Services.Service-1]
[Services.Service-1.healthcheck]
path = "/health"
scheme = "http"
```
??? example "Additional HTTP Headers -- Using the File Provider"
```toml
[Services]
[Services.Service-1]
[Servicess.Service-1.healthcheck]
path = "/health"
[Service.Service-1.healthcheck.headers]
My-Custom-Header = "foo"
My-Header = "bar"
```