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

229
docs/content/reference/routing-configuration/kubernetes/crd/tcp/ingressroutetcp.md Normal file
View file

@ -0,0 +1,229 @@
---
title: "Kubernetes IngressRouteTCP"
description: "An IngressRouteTCP is a Traefik CRD is in charge of connecting incoming TCP connections to the Services that can handle them."
---
`IngressRouteTCP` is the CRD implementation of a [Traefik TCP router](../../../tcp/router/rules-and-priority.md).
Before creating `IngressRouteTCP` 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 `IngressRouteTCP` kind and other Traefik-specific resources.
!!! note "General"
If both HTTP routers and TCP routers are connected to the same EntryPoint, the TCP routers will apply before the HTTP routers. If no matching route is found for the TCP routers, then the HTTP routers will take over.
## Configuration Example
You can declare an `IngressRouteTCP` as detailed below:
```yaml tab="IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
name: ingressroutetcpfoo
namespace: apps
spec:
entryPoints:
- footcp
routes:
- match: HostSNI(`*`)
priority: 10
middlewares:
- name: middleware1
namespace: default
services:
- name: foo
port: 8080
weight: 10
proxyProtocol:
version: 1
serversTransport: transport
nativeLB: true
nodePortLB: true
tls: false
tls:
secretName: supersecret
options:
name: opt
namespace: default
certResolver: foo
domains:
- main: example.net
sans:
- a.example.net
- b.example.net
passthrough: false
```
## Configuration Options
| Field | Description | Default | Required |
|-------------------------------------|-----------------------------|-------------------------------------------|-----------------------|
| `entryPoints` | List of entrypoints names. | | No |
| `routes` | List of routes. | | Yes |
| `routes[n].match` | Defines the [rule](../../../tcp/router/rules-and-priority.md#rules) of the underlying router. | | Yes |
| `routes[n].priority` | Defines the [priority](../../../tcp/router/rules-and-priority.md#priority) to disambiguate rules of the same length, for route matching. | | No |
| `routes[n].middlewares[n].name` | Defines the [MiddlewareTCP](./middlewaretcp.md) name. | | Yes |
| `routes[n].middlewares[n].namespace` | Defines the [MiddlewareTCP](./middlewaretcp.md) namespace. | ""| No|
| `routes[n].services` | List of [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) definitions. | | No |
| `routes[n].services[n].name` | Defines the name of a [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/). | | Yes |
| `routes[n].services[n].port` | Defines the port of a [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/). This can be a reference to a named port.| | Yes |
| `routes[n].services[n].weight` | Defines the weight to apply to the server load balancing. | 1 | No |
| `routes[n].services[n].proxyProtocol` | Defines the [PROXY protocol](../../../../install-configuration/entrypoints.md#proxyprotocol-and-load-balancers) configuration. | | No |
| `routes[n].services[n].proxyProtocol.version` | Defines the [PROXY protocol](../../../../install-configuration/entrypoints.md#proxyprotocol-and-load-balancers) version. | | No |
| `routes[n].services[n].serversTransport` | Defines the [ServersTransportTCP](./serverstransporttcp.md).<br />The `ServersTransport` namespace is assumed to be the [Kubernetes service](https://kubernetes.io/docs/concepts/services-networking/service/) namespace. | | No |
| `routes[n].services[n].nativeLB` | Controls, when creating the load-balancer, whether the LB's children are directly the pods IPs or if the only child is the Kubernetes Service clusterIP. See [here](#nativelb) for more information. | false | No |
| `routes[n].services[n].nodePortLB` | Controls, when creating the load-balancer, whether the LB's children are directly the nodes internal IPs using the nodePort when the service type is `NodePort`. It allows services to be reachable when Traefik runs externally from the Kubernetes cluster but within the same network of the nodes. | false | No |
| `tls` | Defines [TLS](../../../../install-configuration/tls/certificate-resolvers/overview.md) certificate configuration. | | No |
| `tls.secretName` | Defines the [secret](https://kubernetes.io/docs/concepts/configuration/secret/) name used to store the certificate (in the `IngressRoute` namespace). | "" | No |
| `tls.options` | Defines the reference to a [TLSOption](../http/tlsoption.md). | "" | No |
| `tls.options.name` | Defines the [TLSOption](../http/tlsoption.md) name. | "" | No |
| `tls.options.namespace` | Defines the [TLSOption](../http/tlsoption.md) namespace. | "" | No |
| `tls.certResolver` | Defines the reference to a [CertResolver](../../../../install-configuration/tls/certificate-resolvers/overview.md). | "" | No |
| `tls.domains` | List of domains. | "" | No |
| `tls.domains[n].main` | Defines the main domain name. | "" | No |
| `tls.domains[n].sans` | List of SANs (alternative domains). | "" | No |
| `tls.passthrough` | If `true`, delegates the TLS termination to the backend. | false | No |
### ExternalName Service
Traefik connect to a backend with a domain and a port. However, Kubernetes [ExternalName Service](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) can be defined without any port. Accordingly, Traefik supports defining a port in two ways:
- only on `IngressRouteTCP` service
- on both sides, you'll be warned if the ports don't match, and the `IngressRouteTCP` service port is used
Thus, in case of two sides port definition, Traefik expects a match between ports.
=== "Ports defined on Resource"
```yaml tab="IngressRouteTCP"
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
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="IngressRouteTCP"
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
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="IngressRouteTCP"
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
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
```
### NativeLB
To avoid creating the server load-balancer with the pods IPs and use Kubernetes Service `clusterIP` directly, one should set the `NativeLB` option to true. By default, `NativeLB` is false.
```yaml tab="IngressRouteTCP"
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
name: test.route
namespace: default
spec:
entryPoints:
- foo
routes:
- match: HostSNI(`*`)
services:
- name: svc
port: 80
# Here, nativeLB instructs to build the servers load balancer with the Kubernetes Service clusterIP only.
nativeLB: true
```
```yaml tab="Service"
apiVersion: v1
kind: Service
metadata:
name: svc
namespace: default
spec:
type: ClusterIP
...
```

49
docs/content/reference/routing-configuration/kubernetes/crd/tcp/middlewaretcp.md Normal file
View file

@ -0,0 +1,49 @@
---
title: "Kubernetes MiddlewareTCP"
description: "Learn how to configure a Traefik Proxy Kubernetes Middleware to reach TCP Services, which handle incoming requests. Read the technical documentation."
---
`MiddlewareTCP` is the CRD implementation of a [Traefik TCP middleware](../../../tcp/middlewares/overview.md).
Before creating `MiddlewareTCP` 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 `MiddlewareTCP` 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.
## Configuration Example
```yaml tab="MiddlewareTCP"
apiVersion: traefik.io/v1alpha1
kind: MiddlewareTCP
metadata:
name: ipallowlist
spec:
ipAllowList:
sourceRange:
- 127.0.0.1/32
- 192.168.1.7
```
```yaml tab="IngressRouteTCP"
apiVersion: traefik.io/v1alpha1
kind: IngressRouteTCP
metadata:
name: ingressroutebar
spec:
entryPoints:
- web
routes:
- match: Host(`example.com`) && PathPrefix(`/allowlist`)
kind: Rule
services:
- name: whoami
port: 80
middlewares:
- name: ipallowlist
namespace: foo
```
More information about available TCP middlewares in the dedicated [middlewares section](../../../tcp/middlewares/overview.md).

51
docs/content/reference/routing-configuration/kubernetes/crd/tcp/serverstransporttcp.md Normal file
View file

@ -0,0 +1,51 @@
---
title : 'ServersTransportTCP'
description : 'Understand the service routing configuration for the Kubernetes ServerTransportTCP & Traefik CRD'
---
`ServersTransportTCP` is the CRD implementation of [ServersTransportTCP](../../../tcp/serverstransport.md).
Before creating `ServersTransportTCP` 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 `ServersTransportTCP` kind and other Traefik-specific resources.
!!! tip "Default serversTransportTCP"
If no `serversTransportTCP` is specified, the `default@internal` will be used. The `default@internal` `serversTransportTCP` is created from the install configuration (formerly known as static configuration).
!!! note "ServersTransport reference"
By default, the referenced `ServersTransportTCP` CRD must be defined in the same Kubernetes service namespace.
To reference a `ServersTransportTCP` CRD from another namespace, the value must be of form `namespace-name@kubernetescrd`, and the `allowCrossNamespace` option must be enabled.
If the `ServersTransportTCP` CRD is defined in another provider the cross-provider format `name@provider` should be used.
## Configuration Example
```yaml tab="ServersTransportTCP"
apiVersion: traefik.io/v1alpha1
kind: ServersTransportTCP
metadata:
name: mytransport
namespace: default
spec:
tls:
serverName: example.org
insecureSkipVerify: true
```
## Configuration Options
| Field | Description | Default | Required |
|-------------------------------------|-----------------------------|-------------------------------------------|-----------------------|
| `dialTimeout` | The amount of time to wait until a connection to a server can be established. If zero, no timeout exists. | 30s | No |
| `dialKeepAlive` | The interval between keep-alive probes for an active network connection.<br />If this option is set to zero, keep-alive probes are sent with a default value (currently 15 seconds),<br />if supported by the protocol and operating system. Network protocols or operating systems that do not support keep-alives ignore this field.<br />If negative, keep-alive probes are turned off.| 15s | No |
| `terminationDelay` | Defines the delay to wait before fully terminating the connection, after one connected peer has closed its writing capability.| 100ms | No |
| `tls.serverName` | ServerName used to contact the server. | "" | No |
| `tls.insecureSkipVerify` | Controls whether the server's certificate chain and host name is verified. | false | No |
| `tls.peerCertURI` | Defines the URI used to match against SAN URIs during the server's certificate verification. | "" | No |
| `tls.rootCAsSecrets` | Defines the set of root certificate authorities to use when verifying server certificates.<br />The CA secret must contain a base64 encoded certificate under either a `tls.ca` or a `ca.crt` key.| "" | No |
| `tls.certificatesSecrets` | Certificates to present to the server for mTLS.| "" | No |
| `spiffe` | Configures [SPIFFE](../../../../install-configuration/tls/spiffe.md) options. | "" | No |
| `spiffe.ids` | Defines the allowed SPIFFE IDs. This takes precedence over the SPIFFE `trustDomain`. |""| No |
| `spiffe.trustDomain` | Defines the allowed SPIFFE trust domain. | "" | No |

6
docs/content/reference/routing-configuration/kubernetes/crd/tcp/tlsoption.md Normal file
View file

@ -0,0 +1,6 @@
---
title: "TLSOption"
description: "TLS Options in Traefik Proxy"
---
--8<-- "content/reference/routing-configuration/kubernetes/crd/http/tlsoption.md"

6
docs/content/reference/routing-configuration/kubernetes/crd/tcp/tlsstore.md Normal file
View file

@ -0,0 +1,6 @@
---
title: "TLSStore"
description: "TLS Store in Traefik Proxy"
---
--8<-- "content/reference/routing-configuration/kubernetes/crd/http/tlsstore.md"