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

New Routing Reference Documentation

Browse source
This commit is contained in:
Sheddy 2025-03-10 14:28:06 +00:00 • committed by GitHub
parent 3c99135bf9
commit b7170df2c3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
65 changed files with 12109 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

561
docs/content/reference/routing-configuration/kubernetes/crd/http/ingressroute.md Normal file
View file

@ -0,0 +1,561 @@
---
title: "Kubernetes IngressRoute"
description: "An IngressRoute is a Traefik CRD is in charge of connecting incoming requests to the Services that can handle them in HTTP."
---
`IngressRoute` is the CRD implementation of a [Traefik HTTP router](../../../http/router/rules-and-priority.md).
Before creating `IngressRoute` objects, you need to apply the [Traefik Kubernetes CRDs](https://doc.traefik.io/traefik/reference/dynamic-configuration/kubernetes-crd/#definitions) to your Kubernetes cluster.
This registers the `IngressRoute` kind and other Traefik-specific resources.
## Configuration Example
You can declare an `IngressRoute` as detailed below:
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: test-name
namespace: apps
spec:
entryPoints:
- web
routes:
- kind: Rule
# Rule on the Host
match: Host(`test.example.com`)
# Attach a middleware
middlewares:
- name: middleware1
namespace: apps
# Enable Router observability
observability:
accesslogs: true
metrics: true
tracing: true
# Set a pirority
priority: 10
services:
# Target a Kubernetes Support
- kind: Service
name: foo
namespace: apps
# Customize the connection between Traefik and the backend
passHostHeader: true
port: 80
responseForwarding:
flushInterval: 1ms
scheme: https
sticky:
cookie:
httpOnly: true
name: cookie
secure: true
strategy: RoundRobin
weight: 10
tls:
# Generate a TLS certificate using a certificate resolver
certResolver: foo
domains:
- main: example.net
sans:
- a.example.net
- b.example.net
# Customize the TLS options
options:
name: opt
namespace: apps
# Add a TLS certificate from a Kubernetes Secret
secretName: supersecret
```
## Configuration Options
| Field | Description | Default | Required |
|:------|:----------------------------------------------------------|:---------------------|:---------|
| `entryPoints` | List of [entry points](../../../../install-configuration/entrypoints.md) names.<br />If not specified, HTTP routers will accept requests from all EntryPoints in the list of default EntryPoints. | | No |
| `routes` | List of routes. | | Yes |
| `routes[n].kind` | Kind of router matching, only `Rule` is allowed yet. | "Rule" | No |
| `routes[n].match` | Defines the [rule](../../../http/router/rules-and-priority.md#rules) corresponding to an underlying router. | | Yes |
| `routes[n].priority` | Defines the [priority](../../../http/router/rules-and-priority.md#priority-calculation) to disambiguate rules of the same length, for route matching.<br />If not set, the priority is directly equal to the length of the rule, and so the longest length has the highest priority.<br />A value of `0` for the priority is ignored, the default rules length sorting is used. | 0 | No |
| `routes[n].middlewares` | List of middlewares to attach to the IngressRoute. <br />More information [here](#middleware). | "" | No |
| `routes[n].`<br />`middlewares[m].`<br />`name` | Middleware name.<br />The character `@` is not authorized. <br />More information [here](#middleware). | | Yes |
| `routes[n].`<br />`middlewares[m].`<br />`namespace` | Middleware namespace.<br />Can be empty if the middleware belongs to the same namespace as the IngressRoute. <br />More information [here](#middleware). | | No |
| `routes[n].`<br />`observability.`<br />`accesslogs` | Defines whether the route will produce [access-logs](../../../../install-configuration/observability/logs-and-accesslogs.md). See [here](../../../http/router/observability.md) for more information. | false | No |
| `routes[n].`<br />`observability.`<br />`metrics` | Defines whether the route will produce [metrics](../../../../install-configuration/observability/metrics.md). See [here](../../../http/router/observability.md) for more information. | false | No |
| `routes[n].`<br />`observability.`<br />`tracing` | Defines whether the route will produce [traces](../../../../install-configuration/observability/tracing.md). See [here](../../../http/router/observability.md) for more information. | false | No |
| `routes[n].`<br />`services` | List of any combination of TraefikService and [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/). <br />More information [here](#externalname-service). | | No |
| `routes[n].`<br />`services[m].`<br />`kind` | Kind of the service targeted.<br />Two values allowed:<br />- **Service**: Kubernetes Service<br /> **TraefikService**: Traefik Service.<br />More information [here](#externalname-service). | "Service" | No |
| `routes[n].`<br />`services[m].`<br />`name` | Service name.<br />The character `@` is not authorized. <br />More information [here](#middleware). | | Yes |
| `routes[n].`<br />`services[m].`<br />`namespace` | Service namespace.<br />Can be empty if the service belongs to the same namespace as the IngressRoute. <br />More information [here](#externalname-service). | | No |
| `routes[n].`<br />`services[m].`<br />`port` | Service port (number or port name).<br />Evaluated only if the kind is **Service**. | | No |
| `routes[n].`<br />`services[m].`<br />`responseForwarding.`<br />`flushInterval` | Interval, in milliseconds, in between flushes to the client while copying the response body.<br />A negative value means to flush immediately after each write to the client.<br />This configuration is ignored when a response is a streaming response; for such responses, writes are flushed to the client immediately.<br />Evaluated only if the kind is **Service**. | 100ms | No |
| `routes[n].`<br />`services[m].`<br />`scheme` | Scheme to use for the request to the upstream Kubernetes Service.<br />Evaluated only if the kind is **Service**. | "http"<br />"https" if `port` is 443 or contains the string *https*. | No |
| `routes[n].`<br />`services[m].`<br />`serversTransport` | Name of ServersTransport resource to use to configure the transport between Traefik and your servers.<br />Evaluated only if the kind is **Service**. | "" | No |
| `routes[n].`<br />`services[m].`<br />`passHostHeader` | Forward client Host header to server.<br />Evaluated only if the kind is **Service**. | true | No |
| `routes[n].`<br />`services[m].`<br />`healthCheck.scheme` | Server URL scheme for the health check endpoint.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#externalname-service). | "" | No |
| `routes[n].`<br />`services[m].`<br />`healthCheck.mode` | Health check mode.<br /> If defined to grpc, will use the gRPC health check protocol to probe the server.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#externalname-service). | "http" | No |
| `routes[n].`<br />`services[m].`<br />`healthCheck.path` | Server URL path for the health check endpoint.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#externalname-service). | "" | No |
| `routes[n].`<br />`services[m].`<br />`healthCheck.interval` | Frequency of the health check calls.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#externalname-service). | "100ms" | No |
| `routes[n].`<br />`services[m].`<br />`healthCheck.method` | HTTP method for the health check endpoint.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#externalname-service). | "GET" | No |
| `routes[n].`<br />`services[m].`<br />`healthCheck.status` | Expected HTTP status code of the response to the health check request.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type ExternalName.<br />If not set, expect a status between 200 and 399.<br />Evaluated only if the kind is **Service**. | | No |
| `routes[n].`<br />`services[m].`<br />`healthCheck.port` | URL port for the health check endpoint.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#externalname-service). | | No |
| `routes[n].`<br />`services[m].`<br />`healthCheck.timeout` | Maximum duration to wait before considering the server unhealthy.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#externalname-service). | "5s" | No |
| `routes[n].`<br />`services[m].`<br />`healthCheck.hostname` | Value in the Host header of the health check request.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#externalname-service). | "" | No |
| `routes[n].`<br />`services[m].`<br />`healthCheck.`<br />`followRedirect` | Follow the redirections during the healtchcheck.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#externalname-service). | true | No |
| `routes[n].`<br />`services[m].`<br />`healthCheck.headers` | Map of header to send to the health check endpoint<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#externalname-service)). | | No |
| `routes[n].`<br />`services[m].`<br />`sticky.`<br />`cookie.name` | Name of the cookie used for the stickiness.<br />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.<br />On subsequent requests, to keep the session alive with the same server, the client should send the cookie with the value set.<br />If the server pecified in the cookie becomes unhealthy, the request will be forwarded to a new server (and the cookie will keep track of the new server).<br />Evaluated only if the kind is **Service**. | "" | No |
| `routes[n].`<br />`services[m].`<br />`sticky.`<br />`cookie.httpOnly` | Allow the cookie can be accessed by client-side APIs, such as JavaScript.<br />Evaluated only if the kind is **Service**. | false | No |
| `routes[n].`<br />`services[m].`<br />`sticky.`<br />`cookie.secure` | Allow the cookie can only be transmitted over an encrypted connection (i.e. HTTPS).<br />Evaluated only if the kind is **Service**. | false | No |
| `routes[n].`<br />`services[m].`<br />`sticky.`<br />`cookie.sameSite` | [SameSite](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) policy<br />Allowed values:<br />-`none`<br />-`lax`<br />`strict`<br />Evaluated only if the kind is **Service**. | "" | No |
| `routes[n].`<br />`services[m].`<br />`sticky.`<br />`cookie.maxAge` | Number of seconds until the cookie expires.<br />Negative number, the cookie expires immediately.<br />0, the cookie never expires.<br />Evaluated only if the kind is **Service**. | 0 | No |
| `routes[n].`<br />`services[m].`<br />`strategy` | Load balancing strategy between the servers.<br />RoundRobin is the only supported value yet.<br />Evaluated only if the kind is **Service**. | "RoundRobin" | No |
| `routes[n].`<br />`services[m].`<br />`weight` | Service weight.<br />To use only to refer to WRR TraefikService | "" | No |
| `routes[n].`<br />`services[m].`<br />`nativeLB` | Allow using the Kubernetes Service load balancing between the pods instead of the one provided by Traefik.<br /> Evaluated only if the kind is **Service**. | false | No |
| `routes[n].`<br />`services[m].`<br />`nodePortLB` | Use the nodePort IP address when the service type is NodePort.<br />It allows services to be reachable when Traefik runs externally from the Kubernetes cluster but within the same network of the nodes.<br />Evaluated only if the kind is **Service**. | false | No |
| `tls` | TLS configuration.<br />Can be an empty value(`{}`):<br />A self signed is generated in such a case<br />(or the [default certificate](tlsstore.md) is used if it is defined.) | | No |
| `tls.secretName` | [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) name used to store the certificate (in the same namesapce as the `IngressRoute`) | "" | No |
| `tls.`<br />`options.name` | Name of the [`TLSOption`](tlsoption.md) to use.<br />More information [here](#tls-options). | "" | No |
| `tls.`<br />`options.namespace` | Namespace of the [`TLSOption`](tlsoption.md) to use. | "" | No |
| `tls.certResolver` | Name of the [Certificate Resolver](../../../../install-configuration/tls/certificate-resolvers/overview.md) to use to generate automatic TLS certificates. | "" | No |
| `tls.domains` | List of domains to serve using the certificates generates (one `tls.domain`= one certificate).<br />More information in the [dedicated section](../../../../install-configuration/tls/certificate-resolvers/acme.md#domain-definition). | | No |
| `tls.`<br />`domains[n].main` | Main domain name | "" | Yes |
| `tls.`<br />`domains[n].sans` | List of alternative domains (SANs) | | No |
### ExternalName Service
Traefik backends creation needs a port to be set, however Kubernetes [ExternalName Service](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) could be defined without any port. Accordingly, Traefik supports defining a port in two ways:
- only on `IngressRoute` service
- on both sides, you'll be warned if the ports don't match, and the `IngressRoute` service port is used
Thus, in case of two sides port definition, Traefik expects a match between ports.
=== "Ports defined on Resource"
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: test.route
namespace: apps
spec:
entryPoints:
- foo
routes:
- match: Host(`example.net`)
kind: Rule
services:
- name: external-svc
port: 80
```
```yaml tab="Service ExternalName"
apiVersion: v1
kind: Service
metadata:
name: external-svc
namespace: apps
spec:
externalName: external.domain
type: ExternalName
```
=== "Port defined on the Service"
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: test.route
namespace: apps
spec:
entryPoints:
- foo
routes:
- match: Host(`example.net`)
kind: Rule
services:
- name: external-svc
```
```yaml tab="Service ExternalName"
apiVersion: v1
kind: Service
metadata:
name: external-svc
namespace: apps
spec:
externalName: external.domain
type: ExternalName
ports:
- port: 80
```
=== "Port defined on both sides"
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: test.route
namespace: apps
spec:
entryPoints:
- foo
routes:
- match: Host(`example.net`)
kind: Rule
services:
- name: external-svc
port: 80
```
```yaml tab="Service ExternalName"
apiVersion: v1
kind: Service
metadata:
name: external-svc
namespace: apps
spec:
externalName: external.domain
type: ExternalName
ports:
- port: 80
```
### Middleware
- You can attach a list of [middlewares](../../../http/middlewares/overview.md)
to each HTTP router.
- The middlewares will take effect only if the rule matches, and before forwarding
the request to the service.
- Middlewares are applied in the same order as their declaration in **router**.
- In Kubernetes, the option `middleware` allow you to attach a middleware using its
name and namespace (the namespace can be omitted when the Middleware is in the
same namespace as the IngressRoute)
??? example "IngressRoute attached to a few middlewares"
```yaml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: my-app
namespace: apps
spec:
entryPoints:
- websecure
routes:
- match: Host(`example.com`)
kind: Rule
middlewares:
# same namespace as the IngressRoute
- name: middleware01
# default namespace
- name: middleware02
namespace: apps
# Other namespace
- name: middleware03
namespace: other-ns
services:
- name: whoami
port: 80
```
??? abstract "routes.services.kind"
As the field `name` can reference different types of objects, use the field `kind` to avoid any ambiguity.
The field `kind` allows the following values:
- `Service` (default value): to reference a [Kubernetes Service](https://kubernetes.io/docs/concepts/services-networking/service/)
- `TraefikService`: to reference an object [`TraefikService`](../http/traefikservice.md)
### Port Definition
Traefik backends creation needs a port to be set, however Kubernetes [ExternalName Service](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) could be defined without any port. Accordingly, Traefik supports defining a port in two ways:
- only on `IngressRoute` service
- on both sides, you'll be warned if the ports don't match, and the `IngressRoute` service port is used
Thus, in case of two sides port definition, Traefik expects a match between ports.
??? example
```yaml tab="IngressRoute"
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: test.route
namespace: default
spec:
entryPoints:
- foo
routes:
- match: Host(`example.net`)
kind: Rule
services:
- name: external-svc
port: 80
---
apiVersion: v1
kind: Service
metadata:
name: external-svc
namespace: default
spec:
externalName: external.domain
type: ExternalName
```
```yaml tab="ExternalName Service"
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: test.route
namespace: default
spec:
entryPoints:
- foo
routes:
- match: Host(`example.net`)
kind: Rule
services:
- name: external-svc
---
apiVersion: v1
kind: Service
metadata:
name: external-svc
namespace: default
spec:
externalName: external.domain
type: ExternalName
ports:
- port: 80
```
```yaml tab="Both sides"
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: test.route
namespace: default
spec:
entryPoints:
- foo
routes:
- match: Host(`example.net`)
kind: Rule
services:
- name: external-svc
port: 80
---
apiVersion: v1
kind: Service
metadata:
name: external-svc
namespace: default
spec:
externalName: external.domain
type: ExternalName
ports:
- port: 80
```
### TLS Options
The `options` field enables fine-grained control of the TLS parameters.
It refers to a [TLSOption](./tlsoption.md) and will be applied only if a `Host`
rule is defined.
#### Server Name Association
A TLS options reference is always mapped to the host name found in the `Host`
part of the rule, but neither to a router nor a router rule.
There could also be several `Host` parts in a rule.
In such a case the TLS options reference would be mapped to as many host names.
A TLS option is picked from the mapping mentioned above and based on the server
name provided during the TLS handshake,
and it all happens before routing actually occurs.
In the case of domain fronting,
if the TLS options associated with the Host Header and the SNI are different then
Traefik will respond with a status code `421`.
#### Conflicting TLS Options
Since a TLS options reference is mapped to a host name, if a configuration introduces
a situation where the same host name (from a `Host` rule) gets matched with two
TLS options references, a conflict occurs, such as in the example below.
??? example
```yaml tab="IngressRoute01"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: IngressRoute01
namespace: apps
spec:
entryPoints:
- foo
routes:
- match: Host(`example.net`)
kind: Rule
tls:
options: foo
...
```
```yaml tab="IngressRoute02"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: IngressRoute02
namespace: apps
spec:
entryPoints:
- foo
routes:
- match: Host(`example.net`)
kind: Rule
tls:
options: bar
...
```
If that happens, both mappings are discarded, and the host name
(`example.net` in the example) for these routers gets associated with
the default TLS options instead.
### Load Balancing
You can declare and use Kubernetes Service load balancing as detailed below:
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutebar
namespace: default
spec:
entryPoints:
- web
routes:
- match: Host(`example.com`) && PathPrefix(`/foo`)
kind: Rule
services:
- name: svc1
namespace: default
- name: svc2
namespace: default
```
```yaml tab="K8s Service"
apiVersion: v1
kind: Service
metadata:
name: svc1
namespace: default
spec:
ports:
- name: http
port: 80
selector:
app: traefiklabs
task: app1
---
apiVersion: v1
kind: Service
metadata:
name: svc2
namespace: default
spec:
ports:
- name: http
port: 80
selector:
app: traefiklabs
task: app2
```
!!! important "Kubernetes Service Native Load-Balancing"
To avoid creating the server load-balancer with the pod IPs and use Kubernetes Service clusterIP directly,
one should set the service `NativeLB` option to true.
Please note that, by default, Traefik reuses the established connections to the backends for performance purposes. This can prevent the requests load balancing between the replicas from behaving as one would expect when the option is set.
By default, `NativeLB` is false.
??? example "Example"
```yaml
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: test.route
namespace: default
spec:
entryPoints:
- foo
routes:
- match: Host(`example.net`)
kind: Rule
services:
- name: svc
port: 80
# Here, nativeLB instructs to build the server load-balancer with the Kubernetes Service clusterIP only.
nativeLB: true
---
apiVersion: v1
kind: Service
metadata:
name: svc
namespace: default
spec:
type: ClusterIP
...
```
### Configuring Backend Protocol
There are 3 ways to configure the backend protocol for communication between Traefik and your pods:
- Setting the scheme explicitly (http/https/h2c)
- Configuring the name of the kubernetes service port to start with https (https)
- Setting the kubernetes service port to use port 443 (https)
If you do not configure the above, Traefik will assume an http connection.

53
docs/content/reference/routing-configuration/kubernetes/crd/http/middleware.md Normal file
View file

@ -0,0 +1,53 @@
---
title: "Traefik Kubernetes Middleware Documentation"
description: "Learn how to configure a Traefik Proxy Kubernetes Middleware to reach Services, which handle incoming requests. Read the technical documentation."
---
`Middleware` is the CRD implementation of a [Traefik middleware](../../../http/middlewares/overview.md).
Before creating `Middleware` objects, you need to apply the [Traefik Kubernetes CRDs](https://doc.traefik.io/traefik/reference/dynamic-configuration/kubernetes-crd/#definitions) to your Kubernetes cluster.
This registers the `Middleware` kind and other Traefik-specific resources.
!!! tip "Cross-provider namespace"
As Kubernetes also has its own notion of namespace, one should not confuse the Kubernetes namespace of a resource (in the reference to the middleware) with the [provider namespace](../../../../install-configuration/providers/overview.md#provider-namespace), when the definition of the middleware comes from another provider. In this context, specifying a namespace when referring to the resource does not make any sense, and will be ignored. Additionally, when you want to reference a Middleware from the CRD Provider, you have to append the namespace of the resource in the resource-name as Traefik appends the namespace internally automatically.
!!! note "Cross-Namespace References"
In the example below, the middleware is defined in the `foo` namespace while being referenced from an IngressRoute in another namespace. To enable such cross-namespace references, the `allowCrossNamespace` option must be enabled in the Traefik [Kubernetes CRD provider](../../../../install-configuration/providers/kubernetes/kubernetes-crd.md#configuration-options) configuration. If you prefer to avoid this requirement, you can define and reference the Middleware within the same namespace.
## Configuration Example
```yaml tab="Middleware"
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: stripprefix
namespace: foo
spec:
stripPrefix:
prefixes:
- /stripit
```
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutebar
spec:
entryPoints:
- web
routes:
- match: Host(`example.com`) && PathPrefix(`/stripit`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: stripprefix
namespace: foo
```
For more information about the available middlewares, navigate to the dedicated [middlewares overview section](../../../http/middlewares/overview.md).

72
docs/content/reference/routing-configuration/kubernetes/crd/http/serverstransport.md Normal file
View file

@ -0,0 +1,72 @@
---
title: "Kubernetes serversTransport"
description: "The Kubernetes ServersTransport allows configuring the connection between Traefik and the HTTP servers in Kubernetes."
---
A `ServersTransport` allows you to configure the connection between Traefik and the HTTP servers in Kubernetes.
Before creating `ServersTransport` objects, you need to apply the [Traefik Kubernetes CRDs](https://doc.traefik.io/traefik/reference/dynamic-configuration/kubernetes-crd/#definitions) to your Kubernetes cluster.
This registers the `ServersTransport` kind and other Traefik-specific resources.
It can be applied on a service using:
- The option `services.serverstransport` on a [`IngressRoute`](./ingressroute.md) (if the service is a Kubernetes Service)
- The option `serverstransport` on a [`TraefikService`](./traefikservice.md) (if the service is a Kubernetes Service)
!!! note "Reference a ServersTransport CRD from another namespace"
The value must be of form `namespace-name@kubernetescrd`, and the `allowCrossNamespace` option must be enabled at the provider level.
## Configuration Example
```yaml tab="serversTransport"
apiVersion: traefik.io/v1alpha1
kind: ServersTransport
metadata:
name: mytransport
namespace: default
spec:
serverName: example.org
insecureSkipVerify: true
```
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: testroute
namespace: default
spec:
entryPoints:
- web
routes:
- match: Host(`example.com`)
kind: Rule
services:
- name: whoami
port: 80
serversTransport: mytransport
```
## Configuration Options
| Field | Description | Default | Required |
|:------|:----------------------------------------------------------|:---------------------|:---------|
| `serverstransport.`<br />`serverName` | Defines the server name that will be used for SNI. | | No |
| `serverstransport.`<br />`insecureSkipVerify` | Controls whether the server's certificate chain and host name is verified. | false | No |
| `serverstransport.`<br />`rootcas` | Set of root certificate authorities to use when verifying server certificates. (for mTLS connections). | | No |
| `serverstransport.`<br />`certificatesSecrets` | Certificates to present to the server for mTLS. | | No |
| `serverstransport.`<br />`maxIdleConnsPerHost` | Maximum idle (keep-alive) connections to keep per-host. | 200 | No |
| `serverstransport.`<br />`disableHTTP2` | Disables HTTP/2 for connections with servers. | false | No |
| `serverstransport.`<br />`peerCertURI` | Defines the URI used to match against SAN URIs during the server's certificate verification. | "" | No |
| `serverstransport.`<br />`forwardingTimeouts.dialTimeout` | Amount of time to wait until a connection to a server can be established.<br />Zero means no timeout. | 30s | No |
| `serverstransport.`<br />`forwardingTimeouts.responseHeaderTimeout` | Amount of time to wait for a server's response headers after fully writing the request (including its body, if any).<br />Zero means no timeout | 0s | No |
| `serverstransport.`<br />`forwardingTimeouts.idleConnTimeout` | Maximum amount of time an idle (keep-alive) connection will remain idle before closing itself.<br />Zero means no timeout. | 90s | No |
| `serverstransport.`<br />`spiffe.ids` | Allow SPIFFE IDs.<br />This takes precedence over the SPIFFE TrustDomain. | | No |
| `serverstransport.`<br />`spiffe.trustDomain` | Allow SPIFFE trust domain. | "" | No |
!!! note "CA Secret"
The CA secret must contain a base64 encoded certificate under either a tls.ca or a ca.crt key.

82
docs/content/reference/routing-configuration/kubernetes/crd/http/tlsoption.md Normal file
View file

@ -0,0 +1,82 @@
---
title: "TLSOption"
description: "TLS Options in Traefik Proxy"
---
The TLS options allow you to configure some parameters of the TLS connection in Traefik.
Before creating `TLSOption` objects or referencing TLS options in the [`IngressRoute`](../http/ingressroute.md) / [`IngressRouteTCP`](../tcp/ingressroutetcp.md) objects, you need to apply the [Traefik Kubernetes CRDs](https://doc.traefik.io/traefik/reference/dynamic-configuration/kubernetes-crd/#definitions) to your Kubernetes cluster.
!!! tip "References and namespaces"
If the optional namespace attribute is not set, the configuration will be applied with the namespace of the `IngressRoute`/`IngressRouteTCP`.
Additionally, when the definition of the TLS option is from another provider, the cross-provider [syntax](../../../../install-configuration/providers/overview.md#provider-namespace) (`middlewarename@provider`) should be used to refer to the TLS option. Specifying a namespace attribute in this case would not make any sense, and will be ignored.
!!! important "TLSOption in Kubernetes"
When using the `TLSOption` resource in Kubernetes, one might setup a default set of options that,
if not explicitly overwritten, should apply to all ingresses.
To achieve that, you'll have to create a `TLSOption` resource with the name `default`.
There may exist only one `TLSOption` with the name `default` (across all namespaces) - otherwise they will be dropped.
To explicitly use a different `TLSOption` (and using the Kubernetes Ingress resources)
you'll have to add an annotation to the Ingress in the following form:
`traefik.ingress.kubernetes.io/router.tls.options: <resource-namespace>-<resource-name>@kubernetescrd`
## Configuration Example
```yaml tab="TLSOption"
apiVersion: traefik.io/v1alpha1
kind: TLSOption
metadata:
name: mytlsoption
namespace: default
spec:
minVersion: VersionTLS12
sniStrict: true
cipherSuites:
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_RSA_WITH_AES_256_GCM_SHA384
clientAuth:
secretNames:
- secret-ca1
- secret-ca2
clientAuthType: VerifyClientCertIfGiven
```
## Configuration Options
| Field | Description | Default | Required |
|:----------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------|:---------|
| `minVersion` | Minimum TLS version that is acceptable. | "VersionTLS12" | No |
| `maxVersion` | Maximum TLS version that is acceptable.<br />We do not recommend setting this option to disable TLS 1.3. | | No |
| `cipherSuites` | List of supported [cipher suites](https://godoc.org/crypto/tls#pkg-constants) for TLS versions up to TLS 1.2.<br />[Cipher suites defined for TLS 1.2 and below cannot be used in TLS 1.3, and vice versa.](https://tools.ietf.org/html/rfc8446)<br />With TLS 1.3, [the cipher suites are not configurable](https://golang.org/doc/go1.12#tls_1_3) (all supported cipher suites are safe in this case). | | No |
| `curvePreferences` | List of the elliptic curves references that will be used in an ECDHE handshake, in preference order.<br />Use curves names from [`crypto`](https://godoc.org/crypto/tls#CurveID) or the [RFC](https://tools.ietf.org/html/rfc8446#section-4.2.7).<br />See [CurveID](https://godoc.org/crypto/tls#CurveID) for more information. | | No |
| `clientAuth.secretNames` | Client Authentication (mTLS) option.<br />List of names of the referenced Kubernetes [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/) (in TLSOption namespace).<br /> The secret must contain a certificate under either a `tls.ca` or a `ca.crt` key. | | No |
| `clientAuth.clientAuthType` | Client Authentication (mTLS) option.<br />Client authentication type to apply. Available values [here](#client-authentication-mtls). | | No |
| `sniStrict` | Allow rejecting connections from clients connections that do not specify a server_name extension.<br />The [default certificate](../../../http/tls/tls-certificates.md#default-certificate) is never served is the option is enabled. | false | No |
| `alpnProtocols` | List of supported application level protocols for the TLS handshake, in order of preference.<br />If the client supports ALPN, the selected protocol will be one from this list, and the connection will fail if there is no mutually supported protocol. | "h2, http/1.1, acme-tls/1" | No |
### Client Authentication (mTLS)
The `clientAuth.clientAuthType` option governs the behaviour as follows:
- `NoClientCert`: disregards any client certificate.
- `RequestClientCert`: asks for a certificate but proceeds anyway if none is provided.
- `RequireAnyClientCert`: requires a certificate but does not verify if it is signed by a CA listed in `clientAuth.caFiles` or in `clientAuth.secretNames`.
- `VerifyClientCertIfGiven`: if a certificate is provided, verifies if it is signed by a CA listed in `clientAuth.caFiles` or in `clientAuth.secretNames`. Otherwise proceeds without any certificate.
- `RequireAndVerifyClientCert`: requires a certificate, which must be signed by a CA listed in `clientAuth.caFiles` or in `clientAuth.secretNames`.
!!! note "CA Secret"
The CA secret must contain a base64 encoded certificate under either a `tls.ca` or a `ca.crt` key.
### Default TLS Option
When no TLS options are specified in an `IngressRoute`/`IngressRouteTCP`, the `default` option is used.
The default behavior is summed up in the table below:
| Configuration | Behavior |
|:--------------------------|:-----------------------------------------------------------|
| No `default` TLS Option | Default internal set of TLS Options by default. |
| One `default` TLS Option | Custom TLS Options applied by default. |
| Many `default` TLS Option | Error log + Default internal set of TLS Options by default. |

39
docs/content/reference/routing-configuration/kubernetes/crd/http/tlsstore.md Normal file
View file

@ -0,0 +1,39 @@
---
title: "TLSStore"
description: "TLS Store in Traefik Proxy"
---
In Traefik, certificates are grouped together in certificates stores.
`TLSStore` is the CRD implementation of a [Traefik TLS Store](../../../http/tls/tls-certificates.md#certificates-stores).
Before creating `TLSStore` objects, you need to apply the [Traefik Kubernetes CRDs](https://doc.traefik.io/traefik/reference/dynamic-configuration/kubernetes-crd/#definitions) to your Kubernetes cluster.
!!! Tip "Default TLS Store"
Traefik currently only uses the TLS Store named "default". This default `TLSStore` should be in a namespace discoverable by Traefik. Since it is used by default on `IngressRoute` and `IngressRouteTCP` objects, there never is a need to actually reference it. This means that you cannot have two stores that are named default in different Kubernetes namespaces. As a consequence, with respect to TLS stores, the only change that makes sense (and only if needed) is to configure the default `TLSStore`.
## Configuration Example
```yaml tab="TLSStore"
apiVersion: traefik.io/v1alpha1
kind: TLSStore
metadata:
name: default
spec:
defaultCertificate:
secretName: supersecret
```
## Configuration Options
| Field | Description | Required |
|:---------------------------------------|:-------------------------|:---------|
| `certificates[n].secretName` | List of Kubernetes [Secrets](https://kubernetes.io/docs/concepts/configuration/secret/), each of them holding a key/certificate pair to add to the store. | No |
| `defaultCertificate.secretName` | Name of the Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/) served for connections without a SNI, or without a matching domain. If no default certificate is provided, Traefik will use the generated one. Do not use if the option `defaultGeneratedCert` is set. | No |
| `defaultGeneratedCert.resolver` | Name of the ACME resolver to use to generate the default certificate.<br /> Do not use if the option `defaultCertificate` is set. | No |
| `defaultGeneratedCert.domain.main` | Main domain used to generate the default certificate.<br /> Do not use if the option `defaultCertificate` is set. | No |
| `defaultGeneratedCert.domain.sans` | List of [Subject Alternative Name](https://en.wikipedia.org/wiki/Subject_Alternative_Name) used to generate the default certificate.<br /> Do not use if the option `defaultCertificate` is set. | No |
!!! note "DefaultCertificate vs DefaultGeneratedCert"
If both `defaultCertificate` and `defaultGeneratedCert` are set, the TLS certificate contained in `defaultCertificate.secretName` is served. The ACME default certificate is not generated.

436
docs/content/reference/routing-configuration/kubernetes/crd/http/traefikservice.md Normal file
View file

@ -0,0 +1,436 @@
---
title: "Traefik Kubernetes Services Documentation"
description: "Learn how to configure routing and load balancing in Traefik Proxy to reach Services, which handle incoming requests. Read the technical documentation."
---
A `TraefikService` is a custom resource that sits on top of the Kubernetes Services. It enables advanced load-balancing features such as a [Weighted Round Robin](#weighted-round-robin) load balancing or a [Mirroring](#mirroring) between your Kubernetes Services.
Services configure how to reach the actual endpoints that will eventually handle incoming requests. In Traefik, the target service can be either a standard [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/)—which exposes a pod—or a TraefikService. The latter allows you to combine advanced load-balancing options like:
- [Weighted Round Robin load balancing](#weighted-round-robin).
- [Mirroring](#mirroring).
## Weighted Round Robin
The WRR is able to load balance the requests between multiple services based on weights. The WRR `TraefikService` allows you to load balance the traffic between Kubernetes Services and other instances of `TraefikService` (another WRR service -, or a mirroring service).
### Configuration Example
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: test-name
namespace: apps
spec:
entryPoints:
- websecure
routes:
- match: Host(`example.com`) && PathPrefix(`/foo`)
kind: Rule
services:
# Set a WRR TraefikService
- name: wrr1
namespace: apps
kind: TraefikService
tls:
# Add a TLS certificate from a Kubernetes Secret
secretName: supersecret
```
```yaml tab="TraefikService WRR Level#1"
apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
name: wrr1
namespace: apps
spec:
weighted:
services:
# Kubernetes Service
- name: svc1
namespace: apps
port: 80
weight: 1
# Second level WRR service
- name: wrr2
namespace: apps
kind: TraefikService
weight: 1
# Mirroring service
# The service is described in the Mirroring example
- name: mirror1
namespace: apps
kind: TraefikService
weight: 1
```
```yaml tab="TraefikService WRR Level#2"
apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
name: wrr2
namespace: apps
spec:
weighted:
services:
# Kubernetes Service
- name: svc2
namespace: apps
port: 80
weight: 1
# Kubernetes Service
- name: svc3
namespace: apps
port: 80
weight: 1
```
```yaml tab="Kubernetes Services"
apiVersion: v1
kind: Service
metadata:
name: svc1
namespace: apps
spec:
ports:
- name: http
port: 80
selector:
app: traefiklabs
task: app1
---
apiVersion: v1
kind: Service
metadata:
name: svc2
namespace: apps
spec:
ports:
- name: http
port: 80
selector:
app: traefiklabs
task: app2
---
apiVersion: v1
kind: Service
metadata:
name: svc3
namespace: apps
spec:
ports:
- name: http
port: 80
selector:
app: traefiklabs
task: app3
```
```yaml tab="Secret"
apiVersion: v1
kind: Secret
metadata:
name: supersecret
namespace: apps
data:
tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0=
tls.key: LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCi0tLS0tRU5EIFBSSVZBVEUgS0VZLS0tLS0=
```
### Configuration Options
| Field | Description | Default | Required |
|:------|:----------------------------------------------------------|:---------------------|:---------|
| `services` | List of any combination of TraefikService and [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/). <br />. | | No |
| `services[m].`<br />`kind` | Kind of the service targeted.<br />Two values allowed:<br />- **Service**: Kubernetes Service<br /> - **TraefikService**: Traefik Service. | "" | No |
| `services[m].`<br />`name` | Service name.<br />The character `@` is not authorized. | "" | Yes |
| `services[m].`<br />`namespace` | Service namespace. | "" | No |
| `services[m].`<br />`port` | Service port (number or port name).<br />Evaluated only if the kind is **Service**. | "" | No |
| `services[m].`<br />`responseForwarding.`<br />`flushInterval` | Interval, in milliseconds, in between flushes to the client while copying the response body.<br />A negative value means to flush immediately after each write to the client.<br />This configuration is ignored when a response is a streaming response; for such responses, writes are flushed to the client immediately.<br />Evaluated only if the kind is **Service**. | 100ms | No |
| `services[m].`<br />`scheme` | Scheme to use for the request to the upstream Kubernetes Service.<br />Evaluated only if the kind is **Service**. | "http"<br />"https" if `port` is 443 or contains the string *https*. | No |
| `services[m].`<br />`serversTransport` | Name of ServersTransport resource to use to configure the transport between Traefik and your servers.<br />Evaluated only if the kind is **Service**. | "" | No |
| `services[m].`<br />`passHostHeader` | Forward client Host header to server.<br />Evaluated only if the kind is **Service**. | true | No |
| `services[m].`<br />`healthCheck.scheme` | Server URL scheme for the health check endpoint.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type `ExternalName`. | "" | No |
| `services[m].`<br />`healthCheck.mode` | Health check mode.<br /> If defined to grpc, will use the gRPC health check protocol to probe the server.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type `ExternalName`. | "http" | No |
| `services[m].`<br />`healthCheck.path` | Server URL path for the health check endpoint.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type `ExternalName`. | "" | No |
| `services[m].`<br />`healthCheck.interval` | Frequency of the health check calls.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName]`ExternalName`. | "100ms" | No |
| `services[m].`<br />`healthCheck.method` | HTTP method for the health check endpoint.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type `ExternalName`. | "GET" | No |
| `services[m].`<br />`healthCheck.status` | Expected HTTP status code of the response to the health check request.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type ExternalName.<br />If not set, expect a status between 200 and 399.<br />Evaluated only if the kind is **Service**. | | No |
| `services[m].`<br />`healthCheck.port` | URL port for the health check endpoint.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type `ExternalName`. | | No |
| `services[m].`<br />`healthCheck.timeout` | Maximum duration to wait before considering the server unhealthy.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type `ExternalName`. | "5s" | No |
| `services[m].`<br />`healthCheck.hostname` | Value in the Host header of the health check request.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type `ExternalName`. | "" | No |
| `services[m].`<br />`healthCheck.`<br />`followRedirect` | Follow the redirections during the healtchcheck.<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type `ExternalName`. | true | No |
| `services[m].`<br />`healthCheck.headers` | Map of header to send to the health check endpoint<br />Evaluated only if the kind is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type `ExternalName`. | | No |
| `services[m].`<br />`sticky.`<br />`cookie.name` | Name of the cookie used for the stickiness.<br />Evaluated only if the kind is **Service**. | Abbreviation of a sha1<br />(ex: `_1d52e`). | No |
| `services[m].`<br />`sticky.`<br />`cookie.httpOnly` | Allow the cookie can be accessed by client-side APIs, such as JavaScript.<br />Evaluated only if the kind is **Service**. | false | No |
| `services[m].`<br />`sticky.`<br />`cookie.secure` | Allow the cookie can only be transmitted over an encrypted connection (i.e. HTTPS).<br />Evaluated only if the kind is **Service**. | false | No |
| `services[m].`<br />`sticky.`<br />`cookie.sameSite` | [SameSite](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) policy.<br />Allowed values:<br />-`none`<br />-`lax`<br />`strict`<br />Evaluated only if the kind is **Service**. | "" | No |
| `services[m].`<br />`sticky.`<br />`cookie.maxAge` | Number of seconds until the cookie expires.<br />Negative number, the cookie expires immediately.<br />0, the cookie never expires.<br />Evaluated only if the kind is **Service**. | 0 | No |
| `services[m].`<br />`strategy` | Load balancing strategy between the servers.<br />RoundRobin is the only supported value yet.<br />Evaluated only if the kind is **Service**. | "RoundRobin" | No |
| `services[m].`<br />`weight` | Service weight.<br />To use only to refer to WRR TraefikService | "" | No |
| `services[m].`<br />`nativeLB` | Allow using the Kubernetes Service load balancing between the pods instead of the one provided by Traefik.<br />Evaluated only if the kind is **Service**. | false | No |
| `services[m].`<br />`nodePortLB` | Use the nodePort IP address when the service type is NodePort.<br />It allows services to be reachable when Traefik runs externally from the Kubernetes cluster but within the same network of the nodes.<br />Evaluated only if the kind is **Service**. | false | No |
| `sticky.`<br />`cookie.name` | Name of the cookie used for the stickiness at the WRR service level.<br />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.<br />On subsequent requests, to keep the session alive with the same server, the client should send the cookie with the value set.<br />If the server pecified in the cookie becomes unhealthy, the request will be forwarded to a new server (and the cookie will keep track of the new server).<br />More information about WRR stickiness [here](#stickiness-on-multiple-levels) | Abbreviation of a sha1<br />(ex: `_1d52e`). | No |
| `sticky.`<br />`cookie.httpOnly` | Allow the cookie used for the stickiness at the WRR service level to be accessed by client-side APIs, such as JavaScript.<br />More information about WRR stickiness [here](#stickiness-on-multiple-levels) | false | No |
| `sticky.`<br />`cookie.secure` | Allow the cookie used for the stickiness at the WRR service level to be only transmitted over an encrypted connection (i.e. HTTPS).<br />More information about WRR stickiness [here](#stickiness-on-multiple-levels) | false | No |
| `sticky.`<br />`cookie.sameSite` | [SameSite](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) policy for the cookie used for the stickiness at the WRR service level.<br />Allowed values:<br />-`none`<br />-`lax`<br />`strict`<br />More information about WRR stickiness [here](#stickiness-on-multiple-levels) | "" | No |
| `sticky.`<br />`cookie.maxAge` | Number of seconds until the cookie used for the stickiness at the WRR service level expires.<br />Negative number, the cookie expires immediately.<br />0, the cookie never expires. | 0 | No |
#### 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.
Sticky sessions, for stickiness to work all the way, must be specified at each load-balancing level.
For instance, in the example below, there is a first level of load-balancing because there is a (Weighted Round Robin) load-balancing of the two `whoami` services,
and there is a second level because each whoami service is a `replicaset` and is thus handled as a load-balancer of servers.
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutebar
namespace: apps
spec:
entryPoints:
- web
routes:
- match: Host(`example.com`) && PathPrefix(`/foo`)
kind: Rule
services:
- name: wrr1
namespace: apps
kind: TraefikService
```
```yaml tab="TraefikService WRR with 2 level of stickiness"
apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
name: wrr1
namespace: apps
spec:
weighted:
services:
- name: whoami1
kind: Service
port: 80
weight: 1
# Stickiness level2 (on the Kubernetes service)
sticky:
cookie:
name: lvl2
- name: whoami2
kind: Service
weight: 1
port: 80
# Stickiness level2 (on the Kubernetes service)
sticky:
cookie:
name: lvl2
# Stickiness level2 (on the WRR service)
sticky:
cookie:
name: lvl1
```
In the example above, 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:
```bash
# Assuming `10.42.0.6` is the IP address of one of the replicas (a pod then) of the `whoami1` service.
curl -H Host:example.com -b "lvl1=default-whoami1-80; lvl2=http://10.42.0.6:80" http://localhost:8000/foo
```
## Mirroring
The mirroring is able to mirror requests sent to a service to other services.
A mirroring service allows you to send the trafiic to many services together:
- The **main** service receives 100% of the traffic,
- The **mirror** services receive a percentage of the traffic.
For example, to upgrade the version of your application. You can set the service that targets current version as the **main** service, and the service of the new version a **mirror** service.
Thus you can start testing the behavior of the new version keeping the current version reachable.
The mirroring `TraefikService` allows you to reference Kubernetes Services and other instances of `TraefikService` (another WRR service -, or a mirroring service).
Please note that by default the whole request is buffered in memory while it is being mirrored.
See the `maxBodySize` option in the example below for how to modify this behavior.
### Configuration Example
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: ingressroutebar
namespace: default
spec:
entryPoints:
- web
routes:
- match: Host(`example.com`) && PathPrefix(`/foo`)
kind: Rule
services:
- name: mirror1
namespace: default
kind: TraefikService
```
```yaml tab="Mirroring from a Kubernetes Service"
# Mirroring from a k8s Service
apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
name: mirror1
namespace: default
spec:
mirroring:
name: svc1 # svc1 receives 100% of the traffic
port: 80
mirrors:
- name: svc2 # svc2 receives a copy of 20% of this traffic
port: 80
percent: 20
- name: svc3 # svc3 receives a copy of 15% of this traffic
kind: TraefikService
percent: 15
```
```yaml tab="Mirroring from a TraefikService (WRR)"
# Mirroring from a Traefik Service
apiVersion: traefik.io/v1alpha1
kind: TraefikService
metadata:
name: mirror1
namespace: default
spec:
mirroring:
name: wrr1 # wrr1 receives 100% of the traffic
kind: TraefikService
mirrors:
- name: svc2 # svc2 receives a copy of 20% of this traffic
port: 80
percent: 20
- name: svc3 # svc3 receives a copy of 10% of this traffic
kind: TraefikService
percent: 10
```
```yaml tab="Kubernetes Services"
apiVersion: v1
kind: Service
metadata:
name: svc1
namespace: default
spec:
ports:
- name: http
port: 80
selector:
app: traefiklabs
task: app1
---
apiVersion: v1
kind: Service
metadata:
name: svc2
namespace: default
spec:
ports:
- name: http
port: 80
selector:
app: traefiklabs
task: app2
```
### Configuration Options
!!!note "Main and mirrored services"
The main service properties are set as the option root level.
The mirrored services properties are set in the `mirrors` list.
| Field | Description | Default | Required |
|:------|:----------------------------------------------------------|:---------------------|:---------|
| `kind` | Kind of the main service.<br />Two values allowed:<br />- **Service**: Kubernetes Service<br />- **TraefikService**: Traefik Service.<br />More information [here](#services) | "" | No |
| `name` | Main service name.<br />The character `@` is not authorized. | "" | Yes |
| `namespace` | Main service namespace.<br />More information [here](#services). | "" | No |
| `port` | Main service port (number or port name).<br />Evaluated only if the kind of the main service is **Service**. | "" | No |
| `responseForwarding.`<br />`flushInterval` | Interval, in milliseconds, in between flushes to the client while copying the response body.<br />A negative value means to flush immediately after each write to the client.<br />This configuration is ignored when a response is a streaming response; for such responses, writes are flushed to the client immediately.<br />Evaluated only if the kind of the main service is **Service**. | 100ms | No |
| `scheme` | Scheme to use for the request to the upstream Kubernetes Service.<br />Evaluated only if the kind of the main service is **Service**. | "http"<br />"https" if `port` is 443 or contains the string *https*. | No |
| `serversTransport` | Name of ServersTransport resource to use to configure the transport between Traefik and the main service's servers.<br />Evaluated only if the kind of the main service is **Service**. | "" | No |
| `passHostHeader` | Forward client Host header to main service's server.<br />Evaluated only if the kind of the main service is **Service**. | true | No |
| `healthCheck.scheme` | Server URL scheme for the health check endpoint.<br />Evaluated only if the kind of the main service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "" | No |
| `healthCheck.mode` | Health check mode.<br /> If defined to grpc, will use the gRPC health check protocol to probe the server.<br />Evaluated only if the kind of the main service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "http" | No |
| `healthCheck.path` | Server URL path for the health check endpoint.<br />Evaluated only if the kind of the main service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "" | No |
| `healthCheck.interval` | Frequency of the health check calls.<br />Evaluated only if the kind of the main service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "100ms" | No |
| `healthCheck.method` | HTTP method for the health check endpoint.<br />Evaluated only if the kind of the main service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "GET" | No |
| `healthCheck.status` | Expected HTTP status code of the response to the health check request.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type ExternalName.<br />If not set, expect a status between 200 and 399.<br />Evaluated only if the kind of the main service is **Service**. | | No |
| `healthCheck.port` | URL port for the health check endpoint.<br />Evaluated only if the kind of the main service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | | No |
| `healthCheck.timeout` | Maximum duration to wait before considering the server unhealthy.<br />Evaluated only if the kind of the main service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "5s" | No |
| `healthCheck.hostname` | Value in the Host header of the health check request.<br />Evaluated only if the kind of the main service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "" | No |
| `healthCheck.`<br />`followRedirect` | Follow the redirections during the healtchcheck.<br />Evaluated only if the kind of the main service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | true | No |
| `healthCheck.headers` | Map of header to send to the health check endpoint<br />Evaluated only if the kind of the main service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | | No |
| `sticky.`<br />`cookie.name` | Name of the cookie used for the stickiness on the main service.<br />Evaluated only if the kind of the main service is **Service**. | Abbreviation of a sha1<br />(ex: `_1d52e`). | No |
| `sticky.`<br />`cookie.httpOnly` | Allow the cookie can be accessed by client-side APIs, such as JavaScript.<br />Evaluated only if the kind of the main service is **Service**. | false | No |
| `sticky.`<br />`cookie.secure` | Allow the cookie can only be transmitted over an encrypted connection (i.e. HTTPS).<br />Evaluated only if the kind of the main service is **Service**. | false | No |
| `sticky.`<br />`cookie.sameSite` | [SameSite](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) policy.<br />Allowed values:<br />-`none`<br />-`lax`<br />`strict`<br />Evaluated only if the kind of the main service is **Service**. | "" | No |
| `sticky.`<br />`cookie.maxAge` | Number of seconds until the cookie expires.<br />Negative number, the cookie expires immediately.<br />0, the cookie never expires.<br />Evaluated only if the kind of the main service is **Service**. | 0 | No |
| `strategy` | Load balancing strategy between the main service's servers.<br />RoundRobin is the only supported value yet.<br />Evaluated only if the kind of the main service is **Service**. | "RoundRobin" | No |
| `weight` | Service weight.<br />To use only to refer to WRR TraefikService | "" | No |
| `nativeLB` | Allow using the Kubernetes Service load balancing between the pods instead of the one provided by Traefik.<br />Evaluated only if the kind of the main service is **Service**. | false | No |
| `nodePortLB` | Use the nodePort IP address when the service type is NodePort.<br />It allows services to be reachable when Traefik runs externally from the Kubernetes cluster but within the same network of the nodes.<br />Evaluated only if the kind of the main service is **Service**. | false | No |
| `maxBodySize` | Maximum size allowed for the body of the request.<br />If the body is larger, the request is not mirrored.<br />-1 means unlimited size. | -1 | No |
| `mirrors` | List of mirrored services to target.<br /> It can be any combination of TraefikService and [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/). <br />More information [here](#services). | | No |
| `mirrors[m].`<br />`kind` | Kind of the mirrored service targeted.<br />Two values allowed:<br />- **Service**: Kubernetes Service<br />- **TraefikService**: Traefik Service.<br />More information [here](#services) | "" | No |
| `mirrors[m].`<br />`name` | Mirrored service name.<br />The character `@` is not authorized. | "" | Yes |
| `mirrors[m].`<br />`namespace` | Mirrored service namespace.<br />More information [here](#services). | "" | No |
| `mirrors[m].`<br />`port` | Mirrored service port (number or port name).<br />Evaluated only if the kind of the mirrored service is **Service**. | "" | No |
| `mirrors[m].`<br />`percent` | Part of the traffic to mirror in percent (from 0 to 100) | 0 | No |
| `mirrors[m].`<br />`responseForwarding.`<br />`flushInterval` | Interval, in milliseconds, in between flushes to the client while copying the response body.<br />A negative value means to flush immediately after each write to the client.<br />This configuration is ignored when a response is a streaming response; for such responses, writes are flushed to the client immediately.<br />Evaluated only if the kind of the mirrored service is **Service**. | 100ms | No |
| `mirrors[m].`<br />`scheme` | Scheme to use for the request to the mirrored service.<br />Evaluated only if the kind of the mirrored service is **Service**. | "http"<br />"https" if `port` is 443 or contains the string *https*. | No |
| `mirrors[m].`<br />`serversTransport` | Name of ServersTransport resource to use to configure the transport between Traefik and the mirrored service servers.<br />Evaluated only if the kind of the mirrored service is **Service**. | "" | No |
| `mirrors[m].`<br />`passHostHeader` | Forward client Host header to the mirrored service servers.<br />Evaluated only if the kind of the mirrored service is **Service**. | true | No |
| `mirrors[m].`<br />`healthCheck.scheme` | Server URL scheme for the health check endpoint.<br />Evaluated only if the kind of the mirrored service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "" | No |
| `mirrors[m].`<br />`healthCheck.mode` | Health check mode.<br /> If defined to grpc, will use the gRPC health check protocol to probe the server.<br />Evaluated only if the kind of the mirrored service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "http" | No |
| `mirrors[m].`<br />`healthCheck.path` | Server URL path for the health check endpoint.<br />Evaluated only if the kind of the mirrored service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "" | No |
| `mirrors[m].`<br />`healthCheck.interval` | Frequency of the health check calls.<br />Evaluated only if the kind of the mirrored service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "100ms" | No |
| `mirrors[m].`<br />`healthCheck.method` | HTTP method for the health check endpoint.<br />Evaluated only if the kind of the mirrored service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "GET" | No |
| `mirrors[m].`<br />`healthCheck.status` | Expected HTTP status code of the response to the health check request.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type ExternalName.<br />If not set, expect a status between 200 and 399.<br />Evaluated only if the kind of the mirrored service is **Service**. | | No |
| `mirrors[m].`<br />`healthCheck.port` | URL port for the health check endpoint.<br />Evaluated only if the kind of the mirrored service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | | No |
| `mirrors[m].`<br />`healthCheck.timeout` | Maximum duration to wait before considering the server unhealthy.<br />Evaluated only if the kind of the mirrored service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "5s" | No |
| `mirrors[m].`<br />`healthCheck.hostname` | Value in the Host header of the health check request.<br />Evaluated only if the kind of the mirrored service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | "" | No |
| `mirrors[m].`<br />`healthCheck.`<br />`followRedirect` | Follow the redirections during the healtchcheck.<br />Evaluated only if the kind of the mirrored service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | true | No |
| `mirrors[m].`<br />`healthCheck.headers` | Map of header to send to the health check endpoint<br />Evaluated only if the kind of the mirrored service is **Service**.<br />Only for [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) of type [ExternalName](#services). | | No |
| `mirrors[m].`<br />`sticky.`<br />`cookie.name` | Name of the cookie used for the stickiness.<br />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.<br />On subsequent requests, to keep the session alive with the same server, the client should send the cookie with the value set.<br />If the server pecified in the cookie becomes unhealthy, the request will be forwarded to a new server (and the cookie will keep track of the new server).<br />Evaluated only if the kind of the mirrored service is **Service**. | "" | No |
| `mirrors[m].`<br />`sticky.`<br />`cookie.httpOnly` | Allow the cookie can be accessed by client-side APIs, such as JavaScript.<br />Evaluated only if the kind of the mirrored service is **Service**. | false | No |
| `mirrors[m].`<br />`sticky.`<br />`cookie.secure` | Allow the cookie can only be transmitted over an encrypted connection (i.e. HTTPS).<br />Evaluated only if the kind of the mirrored service is **Service**. | false | No |
| `mirrors[m].`<br />`sticky.`<br />`cookie.sameSite` | [SameSite](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite) policy.<br />Allowed values:<br />-`none`<br />-`lax`<br />`strict`<br />Evaluated only if the kind of the mirrored service is **Service**. | "" | No |
| `mirrors[m].`<br />`sticky.`<br />`cookie.maxAge` | Number of seconds until the cookie expires.<br />Negative number, the cookie expires immediately.<br />0, the cookie never expires.<br />Evaluated only if the kind of the mirrored service is **Service**. | 0 | No |
| `mirrors[m].`<br />`strategy` | Load balancing strategy between the servers.<br />RoundRobin is the only supported value yet.<br />Evaluated only if the kind of the mirrored service is **Service**. | "RoundRobin" | No |
| `mirrors[m].`<br />`weight` | Service weight.<br />To use only to refer to WRR TraefikService | "" | No |
| `mirrors[m].`<br />`nativeLB` | Allow using the Kubernetes Service load balancing between the pods instead of the one provided by Traefik.<br />Evaluated only if the kind of the mirrored service is **Service**. | false | No |
| `mirrors[m].`<br />`nodePortLB` | Use the nodePort IP address when the service type is NodePort.<br />It allows services to be reachable when Traefik runs externally from the Kubernetes cluster but within the same network of the nodes.<br />Evaluated only if the kind of the mirrored service is **Service**. | false | No |
| `mirrorBody` | Defines whether the request body should be mirrored. | true | No |