homelab/traefik
1
0
Fork 0
Code Activity

Merge branch v3.5 into master

Browse source
This commit is contained in:
romain 2025-09-09 17:47:13 +02:00
commit c09d3fb03c
243 changed files with 6720 additions and 4386 deletions
Download patch file Download diff file Expand all files Collapse all files

245
docs/content/reference/routing-configuration/http/load-balancing/service.md
View file

@ -100,14 +100,14 @@ labels:
| Field | Description | Required |
|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
| `servers` | Represents individual backend instances for your service | Yes |
| `sticky` | Defines a `Set-Cookie` header is set on the initial response to let the client know which server handles the first response. | No |
| `healthcheck` | Configures health check to remove unhealthy servers from the load balancing rotation. | No |
| `passiveHealthcheck` | Configures the passive health check to remove unhealthy servers from the load balancing rotation. | No |
| `passHostHeader` | Allows forwarding of the client Host header to server. By default, `passHostHeader` is true. | No |
| `serversTransport` | Allows to reference an [HTTP ServersTransport](./serverstransport.md) configuration for the communication between Traefik and your servers. If no `serversTransport` is specified, the `default@internal` will be used. | No |
| `responseForwarding` | Configures how Traefik forwards the response from the backend server to the client. | No |
| `responseForwarding.FlushInterval` | Specifies the interval in between flushes to the client while copying the response body. It is a duration in milliseconds, defaulting to 100ms. A negative value means to flush immediately after each write to the client. The `FlushInterval` is ignored when ReverseProxy recognizes a response as a streaming response; for such responses, writes are flushed to the client immediately. | No |
| <a id="servers" href="#servers" title="#servers">`servers`</a> | Represents individual backend instances for your service | Yes |
| <a id="sticky" href="#sticky" title="#sticky">`sticky`</a> | Defines a `Set-Cookie` header is set on the initial response to let the client know which server handles the first response. | No |
| <a id="healthcheck" href="#healthcheck" title="#healthcheck">`healthcheck`</a> | Configures health check to remove unhealthy servers from the load balancing rotation. | No |
| <a id="passiveHealthcheck" href="#passiveHealthcheck" title="#passiveHealthcheck">`passiveHealthcheck`</a> | Configures the passive health check to remove unhealthy servers from the load balancing rotation. | No |
| <a id="passHostHeader" href="#passHostHeader" title="#passHostHeader">`passHostHeader`</a> | Allows forwarding of the client Host header to server. By default, `passHostHeader` is true. | No |
| <a id="serversTransport" href="#serversTransport" title="#serversTransport">`serversTransport`</a> | Allows to reference an [HTTP ServersTransport](./serverstransport.md) configuration for the communication between Traefik and your servers. If no `serversTransport` is specified, the `default@internal` will be used. | No |
| <a id="responseForwarding" href="#responseForwarding" title="#responseForwarding">`responseForwarding`</a> | Configures how Traefik forwards the response from the backend server to the client. | No |
| <a id="responseForwarding-FlushInterval" href="#responseForwarding-FlushInterval" title="#responseForwarding-FlushInterval">`responseForwarding.FlushInterval`</a> | Specifies the interval in between flushes to the client while copying the response body. It is a duration in milliseconds, defaulting to 100ms. A negative value means to flush immediately after each write to the client. The `FlushInterval` is ignored when ReverseProxy recognizes a response as a streaming response; for such responses, writes are flushed to the client immediately. | No |
#### Servers
@ -117,9 +117,9 @@ Servers represent individual backend instances for your service. The [service lo
| Field | Description | Required |
|----------------|----------------------------------------------------|----------------------------------------------------------------------------------|
| `url` | Points to a specific instance. | Yes for File provider, No for [Docker provider](../../other-providers/docker.md) |
| `weight` | Allows for weighted load balancing on the servers. | No |
| `preservePath` | Allows to preserve the URL path. | No |
| <a id="url" href="#url" title="#url">`url`</a> | Points to a specific instance. | Yes for File provider, No for [Docker provider](../../other-providers/docker.md) |
| <a id="weight" href="#weight" title="#weight">`weight`</a> | Allows for weighted load balancing on the servers. | No |
| <a id="preservePath" href="#preservePath" title="#preservePath">`preservePath`</a> | Allows to preserve the URL path. | No |
#### Health Check
@ -133,19 +133,177 @@ Below are the available options for the health check mechanism:
| Field | Description | Default | Required |
|---------------------|-------------------------------------------------------------------------------------------------------------------------------|---------|----------|
| `path` | Defines the server URL path for the health check endpoint. | "" | Yes |
| `scheme` | Replaces the server URL scheme for the health check endpoint. | | No |
| `mode` | If defined to `grpc`, will use the gRPC health check protocol to probe the server. | http | No |
| `hostname` | Defines the value of hostname in the Host header of the health check request. | "" | No |
| `port` | Replaces the server URL port for the health check endpoint. | | No |
| `interval` | Defines the frequency of the health check calls for healthy targets. | 30s | No |
| `unhealthyInterval` | Defines the frequency of the health check calls for unhealthy targets. When not defined, it defaults to the `interval` value. | 30s | No |
| `timeout` | Defines the maximum duration Traefik will wait for a health check request before considering the server unhealthy. | 5s | No |
| `headers` | Defines custom headers to be sent to the health check endpoint. | | No |
| `followRedirects` | Defines whether redirects should be followed during the health check calls. | true | No |
| `hostname` | Defines the value of hostname in the Host header of the health check request. | "" | No |
| `method` | Defines the HTTP method that will be used while connecting to the endpoint. | GET | No |
| `status` | Defines the expected HTTP status code of the response to the health check request. | | No |
| <a id="path" href="#path" title="#path">`path`</a> | Defines the server URL path for the health check endpoint. | "" | Yes |
| <a id="scheme" href="#scheme" title="#scheme">`scheme`</a> | Replaces the server URL scheme for the health check endpoint. | | No |
| <a id="mode" href="#mode" title="#mode">`mode`</a> | If defined to `grpc`, will use the gRPC health check protocol to probe the server. | http | No |
| <a id="hostname" href="#hostname" title="#hostname">`hostname`</a> | Defines the value of hostname in the Host header of the health check request. | "" | No |
| <a id="port" href="#port" title="#port">`port`</a> | Replaces the server URL port for the health check endpoint. | | No |
| <a id="interval" href="#interval" title="#interval">`interval`</a> | Defines the frequency of the health check calls for healthy targets. | 30s | No |
| <a id="unhealthyInterval" href="#unhealthyInterval" title="#unhealthyInterval">`unhealthyInterval`</a> | Defines the frequency of the health check calls for unhealthy targets. When not defined, it defaults to the `interval` value. | 30s | No |
| <a id="timeout" href="#timeout" title="#timeout">`timeout`</a> | Defines the maximum duration Traefik will wait for a health check request before considering the server unhealthy. | 5s | No |
| <a id="headers" href="#headers" title="#headers">`headers`</a> | Defines custom headers to be sent to the health check endpoint. | | No |
| <a id="followRedirects" href="#followRedirects" title="#followRedirects">`followRedirects`</a> | Defines whether redirects should be followed during the health check calls. | true | No |
| <a id="hostname-2" href="#hostname-2" title="#hostname-2">`hostname`</a> | Defines the value of hostname in the Host header of the health check request. | "" | No |
| <a id="method" href="#method" title="#method">`method`</a> | Defines the HTTP method that will be used while connecting to the endpoint. | GET | No |
| <a id="status" href="#status" title="#status">`status`</a> | Defines the expected HTTP status code of the response to the health check request. | | No |
#### Sticky sessions
When sticky sessions are enabled, a `Set-Cookie` header is set on the initial response to let the client know which server handles the first response.
On subsequent requests, to keep the session alive with the same server, the client should send the cookie with the value set.
##### Stickiness on multiple levels
When chaining or mixing load-balancers (e.g. a load-balancer of servers is one of the "children" of a load-balancer of services), for stickiness to work all the way, the option needs to be specified at all required levels. Which means the client needs to send a cookie with as many key/value pairs as there are sticky levels.
##### 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).
##### Cookie Name
The default cookie name is an abbreviation of a sha1 (ex: `_1d52e`).
##### MaxAge
By default, the affinity cookie will never expire as the `MaxAge` option is set to zero.
This option indicates the number of seconds until the cookie expires.
When set to a negative number, the cookie expires immediately.
##### Secure & HTTPOnly & SameSite flags
By default, the affinity cookie is created without those flags.
One however can change that through configuration.
`SameSite` can be `none`, `lax`, `strict` or empty.
##### Domain
The Domain attribute of a cookie specifies the domain for which the cookie is valid.
By setting the Domain attribute, the cookie can be shared across subdomains (for example, a cookie set for example.com would be accessible to www.example.com, api.example.com, etc.). This is particularly useful in cases where sticky sessions span multiple subdomains, ensuring that the session is maintained even when the client interacts with different parts of the infrastructure.
??? example "Adding Stickiness -- Using the [File Provider](../../../install-configuration/providers/others/file.md)"
```yaml tab="YAML"
## Dynamic configuration
http:
services:
my-service:
loadBalancer:
sticky:
cookie: {}
```
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.my-service]
[http.services.my-service.loadBalancer.sticky.cookie]
```
??? example "Adding Stickiness with custom Options -- Using the [File Provider](../../../install-configuration/providers/others/file.md)"
```yaml tab="YAML"
## Dynamic configuration
http:
services:
my-service:
loadBalancer:
sticky:
cookie:
name: my_sticky_cookie_name
secure: true
domain: mysite.site
httpOnly: true
```
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.my-service]
[http.services.my-service.loadBalancer.sticky.cookie]
name = "my_sticky_cookie_name"
secure = true
httpOnly = true
domain = "mysite.site"
sameSite = "none"
```
??? example "Setting Stickiness on all the required levels -- Using the [File Provider](../../../install-configuration/providers/others/file.md)"
```yaml tab="YAML"
## Dynamic configuration
http:
services:
wrr1:
weighted:
sticky:
cookie:
name: lvl1
services:
- name: whoami1
weight: 1
- name: whoami2
weight: 1
whoami1:
loadBalancer:
sticky:
cookie:
name: lvl2
servers:
- url: http://127.0.0.1:8081
- url: http://127.0.0.1:8082
whoami2:
loadBalancer:
sticky:
cookie:
name: lvl2
servers:
- url: http://127.0.0.1:8083
- url: http://127.0.0.1:8084
```
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.wrr1]
[http.services.wrr1.weighted.sticky.cookie]
name = "lvl1"
[[http.services.wrr1.weighted.services]]
name = "whoami1"
weight = 1
[[http.services.wrr1.weighted.services]]
name = "whoami2"
weight = 1
[http.services.whoami1]
[http.services.whoami1.loadBalancer]
[http.services.whoami1.loadBalancer.sticky.cookie]
name = "lvl2"
[[http.services.whoami1.loadBalancer.servers]]
url = "http://127.0.0.1:8081"
[[http.services.whoami1.loadBalancer.servers]]
url = "http://127.0.0.1:8082"
[http.services.whoami2]
[http.services.whoami2.loadBalancer]
[http.services.whoami2.loadBalancer.sticky.cookie]
name = "lvl2"
[[http.services.whoami2.loadBalancer.servers]]
url = "http://127.0.0.1:8083"
[[http.services.whoami2.loadBalancer.servers]]
url = "http://127.0.0.1:8084"
```
To keep a session open with the same server, the client would then need to specify the two levels within the cookie for each request, e.g. with curl:
```
curl -b "lvl1=whoami1; lvl2=http://127.0.0.1:8081" http://localhost:8000
```
#### Passive Health Check
@ -162,8 +320,8 @@ Below are the available options for the passive health check mechanism:
| Field | Description | Default | Required |
|---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|----------|
| `failureWindow` | Defines the time window during which the failed attempts must occur for the server to be marked as unhealthy. It also defines for how long the server will be considered unhealthy. | 10s | No |
| `maxFailedAttempts` | Defines the number of consecutive failed attempts allowed within the failure window before marking the server as unhealthy. | 1 | No |
| <a id="failureWindow" href="#failureWindow" title="#failureWindow">`failureWindow`</a> | Defines the time window during which the failed attempts must occur for the server to be marked as unhealthy. It also defines for how long the server will be considered unhealthy. | 10s | No |
| <a id="maxFailedAttempts" href="#maxFailedAttempts" title="#maxFailedAttempts">`maxFailedAttempts`</a> | Defines the number of consecutive failed attempts allowed within the failure window before marking the server as unhealthy. | 1 | No |
## Weighted Round Robin (WRR)
@ -173,7 +331,7 @@ This strategy is only available to load balance between services and not between
!!! info "Supported Providers"
This strategy can be defined currently with the [File](../../../install-configuration/providers/others/file.md) or [IngressRoute](../../../install-configuration/providers/kubernetes/kubernetes-ingress.md) providers. To load balance between servers based on weights, the Load Balancer service should be used instead.
This strategy can be defined currently with the [File](../../../install-configuration/providers/others/file.md) or [IngressRoute](../../../install-configuration/providers/kubernetes/kubernetes-crd.md) providers. To load balance between servers based on weights, the Load Balancer service should be used instead.
```yaml tab="Structured (YAML)"
## Dynamic configuration
@ -292,6 +450,37 @@ http:
[[http.services.appv2.loadBalancer.servers]]
url = "http://private-ip-server-2/"
```
## P2C
Power of two choices algorithm is a load balancing strategy that selects two servers at random and chooses the one with the least number of active requests.
??? example "P2C Load Balancing -- Using the [File Provider](../../../install-configuration/providers/others/file.md)"
```yaml tab="YAML"
## Dynamic configuration
http:
services:
my-service:
loadBalancer:
strategy: "p2c"
servers:
- url: "http://private-ip-server-1/"
- url: "http://private-ip-server-2/"
- url: "http://private-ip-server-3/"
```
```toml tab="TOML"
## Dynamic configuration
[http.services]
[http.services.my-service.loadBalancer]
strategy = "p2c"
[[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.servers]]
url = "http://private-ip-server-3/"
```
## Mirroring
@ -303,7 +492,7 @@ The mirroring is able to mirror requests sent to a service to other services. Pl
!!! info "Supported Providers"
This strategy can be defined currently with the [File](../../../install-configuration/providers/others/file.md) or [IngressRoute](../../../install-configuration/providers/kubernetes/kubernetes-ingress.md) providers.
This strategy can be defined currently with the [File](../../../install-configuration/providers/others/file.md) or [IngressRoute](../../../install-configuration/providers/kubernetes/kubernetes-crd.md) providers.
```yaml tab="Structured (YAML)"
## Dynamic configuration