homelab/traefik
1
0
Fork 0
Code Activity

Add dedicated pages for routers and fix doc links in CRDs

Browse source
This commit is contained in:
Romain 2025-10-02 17:32:04 +02:00 • committed by GitHub
parent 614ba391fa
commit 5878238077
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
30 changed files with 485 additions and 231 deletions
Download patch file Download diff file Expand all files Collapse all files

69
docs/content/reference/routing-configuration/udp/routing/router.md Normal file
View file

@ -0,0 +1,69 @@
---
title: "Traefik UDP Routers Documentation"
description: "UDP routers are responsible for connecting incoming UDP packets to the services that can handle them. Read the technical documentation."
---
## UDP Router
A UDP router is in charge of connecting incoming UDP packets to the services that can handle them. Unlike HTTP and TCP routers, UDP routers operate at the transport layer and have unique characteristics due to the connectionless nature of UDP.
!!! important "UDP Router Characteristics"
- UDP is connectionless, so there is no concept of a request URL path or Host SNI to match against
- UDP routers are essentially load-balancers that distribute packets to backend services
- UDP routers can only target UDP services (not HTTP or TCP services)
- Sessions are tracked with configurable timeouts to maintain state between client and backend
## Configuration Example
```yaml tab="Structured (YAML)"
udp:
routers:
my-udp-router:
entryPoints:
- "udp-ep"
- "dns"
service: my-udp-service
```
```toml tab="Structured (TOML)"
[udp.routers]
[udp.routers.my-udp-router]
entryPoints = ["udp-ep", "dns"]
service = "my-udp-service"
```
```yaml tab="Labels"
labels:
- "traefik.udp.routers.my-udp-router.entrypoints=udp-ep,dns"
- "traefik.udp.routers.my-udp-router.service=my-udp-service"
```
```json tab="Tags"
{
"Tags": [
"traefik.udp.routers.my-udp-router.entrypoints=udp-ep,dns",
"traefik.udp.routers.my-udp-router.service=my-udp-service"
]
}
```
## Configuration Options
| Field | Description | Default | Required |
|------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|----------|
| <a id="entryPoints" href="#entryPoints" title="#entryPoints">`entryPoints`</a> | The list of entry points to which the router is attached. If not specified, UDP routers are attached to all UDP entry points. | All UDP entry points | No |
| <a id="service" href="#service" title="#service">`service`</a> | The name of the service that will handle the matched UDP packets. UDP services are typically load balancer services that distribute packets to multiple backend servers. See [UDP Service](../service.md) for details. | | Yes |
## Sessions and Timeout
Even though UDP is connectionless, Traefik's UDP router implementation relies on sessions to maintain state about ongoing communication between clients and backends. This allows the proxy to know where to forward response packets from backends.
Each session has an associated timeout that cleans up inactive sessions after a specified duration of inactivity.
Session timeout can be configured using the `entryPoints.name.udp.timeout` option in the static configuration. See [EntryPoints documentation](../../install-configuration/entrypoints.md) for details.
## Router Naming
- The character `@` is not authorized in the router name
- Router names should be descriptive and follow your naming conventions
- In provider-specific configurations (Docker, Kubernetes), router names are often auto-generated based on service names

112
docs/content/reference/routing-configuration/udp/routing/rules-priority.md Normal file
View file

@ -0,0 +1,112 @@
---
title: "Traefik UDP Routers Rules & Priority Documentation"
description: "In Traefik Proxy, a router is in charge of connecting incoming requests to the Services that can handle them. Read the technical documentation."
---
A router is in charge of connecting incoming requests to the services that can handle them.
In the process, routers may use pieces of [middleware](../../http/middlewares/overview.md) to update the request,
or act before forwarding the request to the service.
Similarly to TCP, as UDP is the transport layer, there is no concept of a request,
so there is no notion of an URL path prefix to match an incoming UDP packet with.
Furthermore, as there is no good TLS support at the moment for multiple hosts,
there is no Host SNI notion to match against either.
Therefore, there is no criterion that could be used as a rule to match incoming packets in order to route them.
So UDP _routers_ at this time are pretty much only load-balancers in one form or another.
!!! tip
UDP routers can only target UDP services (and not HTTP or TCP services).
## Sessions and timeout
Even though UDP is connectionless (and because of that),
the implementation of an UDP router in Traefik relies on what we (and a couple of other implementations) call a `session`.
It means that some state is kept about an ongoing communication between a client and a backend,
notably so that the proxy knows where to forward a response packet from a backend.
As expected, a `timeout` is associated to each of these sessions,
so that they get cleaned out if they go through a period of inactivity longer than a given duration.
Timeout can be configured using the `entryPoints.name.udp.timeout` option as described under [EntryPoints](../../../install-configuration/entrypoints.md)
## EntryPoints
If not specified, UDP routers will accept packets from all defined (UDP) EntryPoints. If one wants to limit the router scope to a set of EntryPoints, one should set the `entryPoints` option.
## Configuration Example
Listens to Every Entry Point
```yaml tab="Structured (YAML)"
udp:
routers:
Router-1:
# By default, routers listen to all UDP entrypoints
# i.e. "other", and "streaming".
service: "service-1"
```
```toml tab="Structured (TOML)"
[udp.routers]
[udp.routers.Router-1]
# By default, routers listen to all UDP entrypoints,
# i.e. "other", and "streaming".
service = "service-1"
```
```yaml tab="Labels"
labels:
- "traefik.udp.routers.Router-1.service=service-1"
```
```json tab="Tags"
{
//...
"Tags": [
"traefik.udp.routers.Router-1.service=service-1"
]
}
```
Listens to Specific EntryPoints
```yaml tab="Structured (YAML)"
udp:
routers:
Router-1:
# does not listen on "other" entry point
entryPoints:
- "streaming"
service: "service-1"
```
```toml tab="Structured (TOML)"
[udp.routers]
[udp.routers.Router-1]
# does not listen on "other" entry point
entryPoints = ["streaming"]
service = "service-1"
```
```yaml tab="Labels"
labels:
- "traefik.udp.routers.Router-1.entryPoints=streaming"
- "traefik.udp.routers.Router-1.service=service-1"
```
```json tab="Tags"
{
//...
"Tags": [
"traefik.udp.routers.Router-1.entryPoints=streaming",
"traefik.udp.routers.Router-1.service=service-1"
]
}
```
!!! info "Service"
There must be one (and only one) UDP [service](../service.md) referenced per UDP router.
Services are the target for the router.
{!traefik-for-business-applications.md!}