homelab/traefik
1
0
Fork 0
Code Activity

Multi-layer routing

Browse source 
Co-authored-by: Romain <rtribotte@users.noreply.github.com>
This commit is contained in:
Simon Delicata 2025-10-22 11:58:05 +02:00 • committed by GitHub
parent 8392503df7
commit d6598f370c
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
37 changed files with 2834 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

20
docs/content/reference/dynamic-configuration/kubernetes-crd-definition-v1.yml
View file

@ -48,6 +48,26 @@ spec:
items:
type: string
type: array
parentRefs:
description: |-
ParentRefs defines references to parent IngressRoute resources for multi-layer routing.
When set, this IngressRoute's routers will be children of the referenced parent IngressRoute's routers.
More info: https://doc.traefik.io/traefik/v3.5/routing/routers/#parentrefs
items:
description: IngressRouteRef is a reference to an IngressRoute resource.
properties:
name:
description: Name defines the name of the referenced IngressRoute
resource.
type: string
namespace:
description: Namespace defines the namespace of the referenced
IngressRoute resource.
type: string
required:
- name
type: object
type: array
routes:
description: Routes defines the list of routes.
items:

20
docs/content/reference/dynamic-configuration/traefik.io_ingressroutes.yaml
View file

@ -48,6 +48,26 @@ spec:
items:
type: string
type: array
parentRefs:
description: |-
ParentRefs defines references to parent IngressRoute resources for multi-layer routing.
When set, this IngressRoute's routers will be children of the referenced parent IngressRoute's routers.
More info: https://doc.traefik.io/traefik/v3.5/routing/routers/#parentrefs
items:
description: IngressRouteRef is a reference to an IngressRoute resource.
properties:
name:
description: Name defines the name of the referenced IngressRoute
resource.
type: string
namespace:
description: Namespace defines the namespace of the referenced
IngressRoute resource.
type: string
required:
- name
type: object
type: array
routes:
description: Routes defines the list of routes.
items:

188
docs/content/reference/routing-configuration/http/routing/multi-layer-routing.md Normal file
View file

@ -0,0 +1,188 @@
---
title: "Multi-Layer Routing"
description: "Learn how to use Traefik's multi-layer routing to create hierarchical router relationships where parent routers can apply middleware before child routers make routing decisions."
---
# Multi-Layer Routing
Hierarchical Router Relationships for Advanced Routing Scenarios.
## Overview
Multi-layer routing enables you to create hierarchical relationships between routers,
where parent routers can process requests through middleware before child routers make final routing decisions.
This feature allows middleware at the parent level to modify requests (adding headers, performing authentication, etc.) that influence how child routers evaluate their rules and route traffic to services.
Multi-layer routing is particularly useful for progressive request enrichment, where each layer adds context to the request, enabling increasingly specific routing decisions:
- **Authentication-Based Routing**: Parent router authenticates requests and adds user context (roles, permissions) as headers, child routers route based on these headers
- **Staged Middleware Application**: Apply common middleware (rate limiting, CORS) at parent level (for a given domain/path), but specific middleware at child level
!!! info "Provider Support"
Multi-layer routing is supported by the following providers:
- **File provider** (YAML, TOML, JSON)
- **KV stores** (Consul, etcd, Redis, ZooKeeper)
- **Kubernetes CRD** (IngressRoute)
Multi-layer routing is not available for other providers (Docker, Kubernetes Ingress, Gateway API, etc.).
## How It Works
```
Request → EntryPoint → Parent Router → Middleware → Child Router A → Service A
↓ → Child Router B → Service B
Modify Request
(e.g., add headers)
```
1. **Request arrives** at an entrypoint
2. **Parent router matches** based on its rule (e.g., ```Host(`example.com`)```)
3. **Parent middleware executes**, potentially modifying the request
4. **One child router matches** based on its rule (which may use modified request attributes)
5. **Request is forwarded** to the matching child router's service
## Building a Router Hierarchy
### Root Routers
- Have no `parentRefs` (top of the hierarchy)
- **Can** have `tls`, `observability`, and `entryPoints` configuration
- Can be either parent routers (with children) or standalone routers (with service)
- **Can** have models applied (non-root routers cannot have models)
### Intermediate Routers
- Reference their parent router(s) via `parentRefs`
- Have one or more child routers
- **Must not** have a `service` defined
- **Must not** have `entryPoints`, `tls`, or `observability` configuration
### Leaf Routers
- Reference their parent router(s) via `parentRefs`
- **Must** have a `service` defined
- **Must not** have `entryPoints`, `tls`, or `observability` configuration
## Configuration Example
??? example "Authentication-Based Routing"
```yaml tab="File (YAML)"
## Dynamic configuration
http:
routers:
# Parent router with authentication
api-parent:
rule: "PathPrefix(`/api`)"
middlewares:
- auth-middleware
entryPoints:
- websecure
tls: {}
# Note: No service defined - this is a parent router
# Child router for admin users
api-admin:
rule: "HeadersRegexp(`X-User-Role`, `admin`)"
service: admin-service
parentRefs:
- api-parent
# Child router for regular users
api-user:
rule: "HeadersRegexp(`X-User-Role`, `user`)"
service: user-service
parentRefs:
- api-parent
middlewares:
auth-middleware:
forwardAuth:
address: "http://auth-service:8080/auth"
authResponseHeaders:
- X-User-Role
- X-User-Name
services:
admin-service:
loadBalancer:
servers:
- url: "http://admin-backend:8080"
user-service:
loadBalancer:
servers:
- url: "http://user-backend:8080"
```
```toml tab="File (TOML)"
## Dynamic configuration
[http.routers]
# Parent router with authentication
[http.routers.api-parent]
rule = "PathPrefix(`/api`)"
middlewares = ["auth-middleware"]
entryPoints = ["websecure"]
[http.routers.api-parent.tls]
# Note: No service defined - this is a parent router
# Child router for admin users
[http.routers.api-admin]
rule = "HeadersRegexp(`X-User-Role`, `admin`)"
service = "admin-service"
parentRefs = ["api-parent"]
# Child router for regular users
[http.routers.api-user]
rule = "HeadersRegexp(`X-User-Role`, `user`)"
service = "user-service"
parentRefs = ["api-parent"]
[http.middlewares]
[http.middlewares.auth-middleware.forwardAuth]
address = "http://auth-service:8080/auth"
authResponseHeaders = ["X-User-Role", "X-User-Name"]
[http.services]
[http.services.admin-service.loadBalancer]
[[http.services.admin-service.loadBalancer.servers]]
url = "http://admin-backend:8080"
[http.services.user-service.loadBalancer]
[[http.services.user-service.loadBalancer.servers]]
url = "http://user-backend:8080"
```
```txt tab="KV (Consul/etcd/Redis/ZK)"
| Key | Value |
|------------------------------------------------------------------------|---------------------------------|
| `traefik/http/routers/api-parent/rule` | `PathPrefix(\`/api\`)` |
| `traefik/http/routers/api-parent/middlewares/0` | `auth-middleware` |
| `traefik/http/routers/api-parent/entrypoints/0` | `websecure` |
| `traefik/http/routers/api-parent/tls` | `true` |
| `traefik/http/routers/api-admin/rule` | `HeadersRegexp(\`X-User-Role\`, \`admin\`)` |
| `traefik/http/routers/api-admin/service` | `admin-service` |
| `traefik/http/routers/api-admin/parentrefs/0` | `api-parent` |
| `traefik/http/routers/api-user/rule` | `HeadersRegexp(\`X-User-Role\`, \`user\`)` |
| `traefik/http/routers/api-user/service` | `user-service` |
| `traefik/http/routers/api-user/parentrefs/0` | `api-parent` |
| `traefik/http/middlewares/auth-middleware/forwardauth/address` | `http://auth-service:8080/auth` |
| `traefik/http/middlewares/auth-middleware/forwardauth/authresponseheaders/0` | `X-User-Role` |
| `traefik/http/middlewares/auth-middleware/forwardauth/authresponseheaders/1` | `X-User-Name` |
| `traefik/http/services/admin-service/loadbalancer/servers/0/url` | `http://admin-backend:8080` |
| `traefik/http/services/user-service/loadbalancer/servers/0/url` | `http://user-backend:8080` |
```
**How it works:**
1. Request to `/api/endpoint` matches `api-parent` router
2. `auth-middleware` (ForwardAuth) validates the request and adds `X-User-Role` header
3. Modified request is evaluated by child routers
4. If `X-User-Role: admin`, `api-admin` router matches and forwards to `admin-service`
5. If `X-User-Role: user`, `api-user` router matches and forwards to `user-service`
{!traefik-for-business-applications.md!}

11
docs/content/reference/routing-configuration/http/routing/router.md
View file

@ -32,6 +32,9 @@ http:
metrics: true
accessLogs: true
tracing: true
parentRefs:
- "parent-router-1"
- "parent-router-2"
service: my-service
```
@ -43,6 +46,7 @@ http:
priority = 10
middlewares = ["auth", "ratelimit"]
service = "my-service"
parentRefs = ["parent-router-1", "parent-router-2"]
[http.routers.my-router.tls]
certResolver = "letsencrypt"
@ -88,15 +92,15 @@ labels:
"traefik.http.routers.my-router.tls.domains[0].sans=www.example.com",
"traefik.http.routers.my-router.observability.metrics=true",
"traefik.http.routers.my-router.observability.accessLogs=true",
"traefik.http.routers.my-router.observability.tracing=true"
"traefik.http.routers.my-router.observability.tracing=true",
]
}
```
## Configuration Options
| Field | Description | Default | Required |
|----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|----------|
| Field | Description | Default | Required |
|----------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|----------|
| <a id="opt-entryPoints" href="#opt-entryPoints" title="#opt-entryPoints">`entryPoints`</a> | The list of entry points to which the router is attached. If not specified, HTTP routers are attached to all entry points. | All entry points | No |
| <a id="opt-rule" href="#opt-rule" title="#opt-rule">`rule`</a> | Rules are a set of matchers configured with values, that determine if a particular request matches specific criteria. If the rule is verified, the router becomes active, calls middlewares, and then forwards the request to the service. See [Rules & Priority](./rules-and-priority.md) for details. | | Yes |
| <a id="opt-priority" href="#opt-priority" title="#opt-priority">`priority`</a> | To avoid path overlap, routes are sorted, by default, in descending order using rules length. The priority is directly equal to the length of the rule, and so the longest length has the highest priority. A value of `0` for the priority is ignored. See [Rules & Priority](./rules-and-priority.md) for details. | Rule length | No |
@ -106,6 +110,7 @@ labels:
| <a id="opt-tls-options" href="#opt-tls-options" title="#opt-tls-options">`tls.options`</a> | The name of the TLS options to use for configuring TLS parameters (cipher suites, min/max TLS version, client authentication, etc.). See [TLS Options](../tls/tls-options.md) for detailed configuration. | `default` | No |
| <a id="opt-tls-domains" href="#opt-tls-domains" title="#opt-tls-domains">`tls.domains`</a> | List of domains and Subject Alternative Names (SANs) for explicit certificate domain specification. When using ACME certificate resolvers, domains are automatically extracted from router rules, making this option optional. | | No |
| <a id="opt-observability" href="#opt-observability" title="#opt-observability">`observability`</a> | Observability configuration for the router. Allows fine-grained control over access logs, metrics, and tracing per router. See [Observability](./observability.md) for details. | Inherited from entry points | No |
| <a id="opt-parentRefs" href="#opt-parentRefs" title="#opt-parentRefs">`parentRefs`</a> | References to parent router names for multi-layer routing. When specified, this router becomes a child router that processes requests after parent routers have applied their middlewares. See [Multi-Layer Routing](../../../../routing/multi-layer-routing.md) for details. | | No |
| <a id="opt-service" href="#opt-service" title="#opt-service">`service`</a> | The name of the service that will handle the matched requests. Services can be load balancer services, weighted round robin, mirroring, or failover services. See [Service](../load-balancing/service.md) for details. | | Yes |
## Router Naming

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

@ -23,6 +23,9 @@ metadata:
spec:
entryPoints:
- web
parentRefs:
- name: parent-gateway
namespace: default # Optional - defaults to same namespace
routes:
- kind: Rule
# Rule on the Host
@ -74,9 +77,12 @@ spec:
## Configuration Options
| Field | Description | Default | Required |
|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
| Field | Description | Default | Required |
|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:---------|
| <a id="opt-entryPoints" href="#opt-entryPoints" title="#opt-entryPoints">`entryPoints`</a> | 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 |
| <a id="opt-parentRefs" href="#opt-parentRefs" title="#opt-parentRefs">`parentRefs`</a> | List of references to parent IngressRoute resources for multi-layer routing. When specified, this IngressRoute's routers become children of the referenced parent IngressRoute's routers. See [Multi-Layer Routing](#multi-layer-routing-with-ingressroutes) section for details. | | No |
| <a id="opt-parentRefsn-name" href="#opt-parentRefsn-name" title="#opt-parentRefsn-name">`parentRefs[n].name`</a> | Name of the referenced parent IngressRoute resource. | | Yes |
| <a id="opt-parentRefsn-namespace" href="#opt-parentRefsn-namespace" title="#opt-parentRefsn-namespace">`parentRefs[n].namespace`</a> | Namespace of the referenced parent IngressRoute resource.<br />If not specified, defaults to the same namespace as the child IngressRoute.<br />Cross-namespace references require `allowCrossNamespace` provider option to be enabled. | | No |
| <a id="opt-routes" href="#opt-routes" title="#opt-routes">`routes`</a> | List of routes. | | Yes |
| <a id="opt-routesn-kind" href="#opt-routesn-kind" title="#opt-routesn-kind">`routes[n].kind`</a> | Kind of router matching, only `Rule` is allowed yet. | "Rule" | No |
| <a id="opt-routesn-match" href="#opt-routesn-match" title="#opt-routesn-match">`routes[n].match`</a> | Defines the [rule](../../../http/routing/rules-and-priority.md#rules) corresponding to an underlying router. | | Yes |
@ -213,6 +219,162 @@ TLS options references, a conflict occurs, such as in the example below.
...
```
If that happens, both mappings are discarded, and the host name
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.
### Multi-Layer Routing with IngressRoutes
Multi-layer routing allows creating hierarchical relationships between IngressRoutes,
where parent IngressRoutes can apply middleware before child IngressRoutes make routing decisions.
This is particularly useful for authentication-based routing,
where a parent IngressRoute authenticates requests and adds context (e.g., user roles as headers),
and child IngressRoutes route based on that context.
When a child IngressRoute references a parent IngressRoute with multiple routes,
**all** parent routers then become parents of **all** child routers.
!!! info "Comprehensive Multi-Layer Routing Documentation"
For detailed information about multi-layer routing concepts, validation rules, and use cases, see the dedicated [Multi-Layer Routing](../../../../routing-configuration/http/routing/multi-layer-routing.md) page.
#### Configuration Requirements
### Root IngressRoutes
- Have no `parentRefs` (top of the hierarchy)
- **Can** have `entryPoints`, `tls`, and `observability` configuration
- Can be either parent IngressRoutes (with children) or standalone IngressRoutes (with service)
### Intermediate IngressRoutes
- Reference their parent IngressRoute(s) via `parentRefs`
- Have one or more child IngressRoutes
- **Must not** have a `service` defined
- **Must not** have `entryPoints`, `tls`, or `observability` configuration
### Leaf IngressRoutes
- Reference their parent IngressRoute(s) via `parentRefs`
- **Must** have a `service` defined
- **Must not** have `entryPoints`, `tls`, or `observability` configuration
!!! warning "Cross-Namespace References"
Cross-namespace parent references require the `allowCrossNamespace` provider option to be enabled.
If disabled, child IngressRoute creation will be skipped with an error logged.
#### Example: Authentication-Based Routing
??? example "Parent IngressRoute with ForwardAuth and Child IngressRoutes"
```yaml tab="Parent IngressRoute"
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: api-parent
namespace: default
spec:
entryPoints:
- websecure
tls:
certResolver: letsencrypt
routes:
# Parent route with authentication - no services
- match: Host(`api.example.com`) && PathPrefix(`/api`)
kind: Rule
middlewares:
- name: auth-middleware
namespace: default
---
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
name: auth-middleware
namespace: default
spec:
forwardAuth:
address: "http://auth-service.default.svc.cluster.local:8080/auth"
authResponseHeaders:
- X-User-Role
- X-User-Name
```
```yaml tab="Child IngressRoutes"
# Child IngressRoute for admin users
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: api-admin
namespace: default
spec:
parentRefs:
- name: api-parent
namespace: default # Optional - defaults to same namespace
routes:
- match: HeadersRegexp(`X-User-Role`, `admin`)
kind: Rule
services:
- name: admin-service
port: 80
---
# Child IngressRoute for regular users
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
name: api-user
namespace: default
spec:
parentRefs:
- name: api-parent
routes:
- match: HeadersRegexp(`X-User-Role`, `user`)
kind: Rule
services:
- name: user-service
port: 80
```
```yaml tab="Services"
apiVersion: v1
kind: Service
metadata:
name: auth-service
namespace: default
spec:
ports:
- port: 8080
selector:
app: auth-service
---
apiVersion: v1
kind: Service
metadata:
name: admin-service
namespace: default
spec:
ports:
- port: 80
selector:
app: admin-backend
---
apiVersion: v1
kind: Service
metadata:
name: user-service
namespace: default
spec:
ports:
- port: 80
selector:
app: user-backend
```
**How it works:**
1. Request to `https://api.example.com/api/endpoint` matches the parent router
2. `auth-middleware` (ForwardAuth) validates the request with `auth-service`
3. `auth-service` returns 200 OK with `X-User-Role` header (e.g., `admin` or `user`)
4. Child routers evaluate rules against the modified request (with `X-User-Role` header)
5. Request is routed to `admin-service` or `user-service` based on the role

2
docs/content/reference/routing-configuration/other-providers/file.toml
View file

@ -7,6 +7,7 @@
middlewares = ["foobar", "foobar"]
service = "foobar"
rule = "foobar"
parentRefs = ["foobar", "foobar"]
ruleSyntax = "foobar"
priority = 42
[http.routers.Router0.tls]
@ -30,6 +31,7 @@
middlewares = ["foobar", "foobar"]
service = "foobar"
rule = "foobar"
parentRefs = ["foobar", "foobar"]
ruleSyntax = "foobar"
priority = 42
[http.routers.Router1.tls]

6
docs/content/reference/routing-configuration/other-providers/file.yaml
View file

@ -11,6 +11,9 @@ http:
- foobar
service: foobar
rule: foobar
parentRefs:
- foobar
- foobar
ruleSyntax: foobar
priority: 42
tls:
@ -39,6 +42,9 @@ http:
- foobar
service: foobar
rule: foobar
parentRefs:
- foobar
- foobar
ruleSyntax: foobar
priority: 42
tls:

3
docs/mkdocs.yml
View file

@ -267,6 +267,7 @@ nav:
- 'Router' : 'reference/routing-configuration/http/routing/router.md'
- 'Rules & Priority' : 'reference/routing-configuration/http/routing/rules-and-priority.md'
- 'Observability': 'reference/routing-configuration/http/routing/observability.md'
- 'Multi-Layer Routing': 'reference/routing-configuration/http/routing/multi-layer-routing.md'
- 'Load Balancing' :
- 'Service' : 'reference/routing-configuration/http/load-balancing/service.md'
- 'ServersTransport' : 'reference/routing-configuration/http/load-balancing/serverstransport.md'
@ -363,6 +364,8 @@ nav:
- 'Features': 'deprecation/features.md'
- 'User Guides':
- 'FastProxy': 'user-guides/fastproxy.md'
- 'Kubernetes and Let''s Encrypt': 'user-guides/crd-acme/index.md'
- 'Kubernetes and cert-manager': 'user-guides/cert-manager.md'
- 'gRPC Examples': 'user-guides/grpc.md'
- 'WebSocket Examples': 'user-guides/websocket.md'
- 'Contributing':