571 lines
16 KiB
Markdown
571 lines
16 KiB
Markdown
---
|
|
created: '2026-04-15T18:16:04+00:00'
|
|
id: 1bb3f6ca-2bd4-4695-8258-69172c16cc0b
|
|
keywords:
|
|
- traefik
|
|
- traefik proxy
|
|
- edge router
|
|
- application proxy
|
|
- docker labels
|
|
- traefik middleware
|
|
- acme
|
|
- letsencrypt
|
|
- certresolver
|
|
- entrypoint
|
|
- traefik v3
|
|
links: []
|
|
modified: '2026-04-15T18:16:04+00:00'
|
|
summary: Comprehensive reference for Traefik Proxy v3.x — an open-source application
|
|
proxy and edge router with auto-discovery, dynamic routing, TLS termination, middleware
|
|
chains, and multi-provider support including Docker, Kubernetes, and cloud platforms.
|
|
tags:
|
|
- reference
|
|
- traefik
|
|
- proxy
|
|
- reverse-proxy
|
|
- load-balancer
|
|
- docker
|
|
- kubernetes
|
|
- routing
|
|
- tls
|
|
- letsencrypt
|
|
- middleware
|
|
- observability
|
|
title: Traefik Proxy — Reference Documentation
|
|
---
|
|
|
|
---
|
|
title: Traefik Proxy — Reference Documentation
|
|
created: 2025-07-15
|
|
modified: 2025-07-15
|
|
tags:
|
|
- reference
|
|
- traefik
|
|
- proxy
|
|
- reverse-proxy
|
|
- load-balancer
|
|
- docker
|
|
- kubernetes
|
|
- routing
|
|
- tls
|
|
- letsencrypt
|
|
- middleware
|
|
- observability
|
|
links:
|
|
- reference/docker-compose.md
|
|
keywords:
|
|
- traefik
|
|
- traefik proxy
|
|
- edge router
|
|
- application proxy
|
|
- docker labels
|
|
- traefik middleware
|
|
- acme
|
|
- letsencrypt
|
|
- certresolver
|
|
- entrypoint
|
|
- traefik v3
|
|
summary: Comprehensive reference for Traefik Proxy v3.x — an open-source application proxy and edge router with auto-discovery, dynamic routing, TLS termination, middleware chains, and multi-provider support including Docker, Kubernetes, and cloud platforms.
|
|
---
|
|
|
|
# Traefik Proxy — Reference Documentation
|
|
|
|
> Source: https://doc.traefik.io/traefik/ (accessed July 2025)
|
|
> Version: v3.x (current)
|
|
|
|
## What is Traefik?
|
|
|
|
Traefik is an open-source **Application Proxy** and edge router that automatically discovers services and dynamically configures routing. Key characteristics:
|
|
|
|
- **Auto-discovery**: Inspects infrastructure (Docker, Kubernetes, etc.) to detect services and configure routes in real time — no restarts, no connection interruptions.
|
|
- **3.3 billion downloads**, 55k+ GitHub stars.
|
|
- Runs across hybrid cloud, multi-cloud, on-prem, and bare metal environments.
|
|
- Supports Kubernetes, Docker Swarm, AWS ECS, and more.
|
|
|
|
### Core Concepts
|
|
|
|
| Concept | Description |
|
|
|---------|-------------|
|
|
| **Entrypoints** | Network entry points. Define port (TCP/UDP) and protocol. |
|
|
| **Routers** | Connect incoming requests to services based on rules. May apply middleware before forwarding. |
|
|
| **Services** | Configure how to reach backend services (load balancing, etc.). |
|
|
| **Providers** | Infrastructure components (orchestrators, container engines, cloud providers, KV stores) that Traefik queries for routing info. Routes hot-reload on provider changes. |
|
|
|
|
### Request Flow
|
|
|
|
```
|
|
Client → Entrypoint → Router (rule match) → [Middlewares] → Service → Backend
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration Overview
|
|
|
|
Traefik has **two distinct configuration layers**:
|
|
|
|
### 1. Install (Startup) Configuration
|
|
|
|
Sets up connections to providers and defines entrypoints. Doesn't change often. Defined via (mutually exclusive, priority order):
|
|
|
|
- **Configuration file**: `traefik.yml`/`traefik.yaml`/`traefik.toml` in `/etc/traefik/`, `$XDG_CONFIG_HOME/`, `$HOME/.config/`, or `./`. Override with `--configFile`.
|
|
- **CLI arguments**: `traefik --help` for full list.
|
|
- **Environment variables**: All install options available as env vars.
|
|
|
|
### 2. Routing Configuration (Dynamic)
|
|
|
|
Defines how requests are handled. Comes from **providers** and is **hot-reloaded** without interruption. Includes:
|
|
|
|
- HTTP/TCP/UDP routers, services, and middlewares
|
|
- TLS certificates
|
|
- Can be added/updated/removed without restarting
|
|
|
|
---
|
|
|
|
## Entrypoints
|
|
|
|
Entrypoints define where Traefik listens for incoming traffic.
|
|
|
|
### Basic Configuration
|
|
|
|
```yaml
|
|
entryPoints:
|
|
web:
|
|
address: ":80"
|
|
http:
|
|
redirections:
|
|
entryPoint:
|
|
to: websecure
|
|
scheme: https
|
|
permanent: true
|
|
|
|
websecure:
|
|
address: ":443"
|
|
http:
|
|
tls: {}
|
|
middlewares:
|
|
- auth@kubernetescrd
|
|
- strip@kubernetescrd
|
|
```
|
|
|
|
### Key Entrypoint Options
|
|
|
|
| Option | Description | Default |
|
|
|--------|-------------|---------|
|
|
| `address` | Port and protocol (e.g., `:80`, `:443`, `:8080/udp`) | — |
|
|
| `http.tls` | Enable default TLS for routers on this entrypoint | `false` |
|
|
| `http.redirections.entryPoint` | Auto-redirect to another entrypoint | — |
|
|
| `http.middlewares` | Default middlewares for all routers on this entrypoint | — |
|
|
| `http.sanitizePath` | Normalize paths (remove `/./`, `/../`, double slashes) | `true` |
|
|
| `forwardedHeaders.trustedIPs` | Trust X-Forwarded-\* headers only from these IPs | — |
|
|
| `forwardedHeaders.insecure` | Trust all forwarded headers | `false` |
|
|
| `http3` | Enable HTTP/3 (uses UDP on same port number) | `false` |
|
|
| `proxyProtocol.trustedIPs` | Enable PROXY protocol from specific IPs | — |
|
|
| `reusePort` | Allow multiple processes on same port (Linux/BSD/macOS) | `false` |
|
|
| `asDefault` | Include in default entrypoints for routers without explicit entrypoints | `false` |
|
|
| `allowACMEByPass` | Allow custom routers to handle ACME challenges | `false` |
|
|
| `observability.accessLogs` | Per-entrypoint access log toggle | `true` |
|
|
| `observability.metrics` | Per-entrypoint metrics toggle | `true` |
|
|
| `observability.tracing` | Per-entrypoint tracing toggle | `true` |
|
|
| `transport.lifecycle.graceTimeOut` | Grace period for active requests on shutdown | `10s` |
|
|
| `transport.respondingTimeouts.readTimeout` | Max duration to read full request | `60s` |
|
|
| `transport.respondingTimeouts.writeTimeout` | Max duration to write response | `0` (none) |
|
|
| `transport.respondingTimeouts.idleTimeout` | Max keep-alive idle duration | `180s` |
|
|
| `http2.maxConcurrentStreams` | Max concurrent HTTP/2 streams per connection | `250` |
|
|
|
|
---
|
|
|
|
## HTTP Routers
|
|
|
|
Routers connect incoming requests to services based on matching rules.
|
|
|
|
### Configuration Example
|
|
|
|
```yaml
|
|
http:
|
|
routers:
|
|
my-router:
|
|
entryPoints:
|
|
- "web"
|
|
- "websecure"
|
|
rule: "Host(`example.com`) && Path(`/api`)"
|
|
priority: 10
|
|
middlewares:
|
|
- "auth"
|
|
- "ratelimit"
|
|
tls:
|
|
certResolver: "letsencrypt"
|
|
options: "modern"
|
|
domains:
|
|
- main: "example.com"
|
|
sans:
|
|
- "www.example.com"
|
|
service: my-service
|
|
observability:
|
|
metrics: true
|
|
accessLogs: true
|
|
tracing: true
|
|
```
|
|
|
|
### Router Configuration Options
|
|
|
|
| Field | Description | Required |
|
|
|-------|-------------|----------|
|
|
| `rule` | Matching rule (matchers: `Host()`, `Path()`, `PathPrefix()`, `Headers()`, `Query()`, `Method()`, etc.) | Yes |
|
|
| `entryPoints` | List of entrypoints (default: all) | No |
|
|
| `service` | Service to forward matched requests to | Yes |
|
|
| `priority` | Rule priority (default: auto by rule length; `0` ignored; negatives supported) | No |
|
|
| `middlewares` | Ordered list of middleware names to apply | No |
|
|
| `tls` | Enable TLS (router only handles HTTPS when set) | No |
|
|
| `tls.certResolver` | ACME certificate resolver name | No |
|
|
| `tls.options` | TLS options name (cipher suites, min/max version, client auth) | No |
|
|
| `tls.domains` | Explicit domain/SAN list for certificates | No |
|
|
| `observability` | Per-router metrics, access logs, tracing overrides | No |
|
|
| `parentRefs` | Parent routers for multi-layer routing | No |
|
|
|
|
### Rule Examples
|
|
|
|
```
|
|
Host(`example.com`)
|
|
Path(`/api`)
|
|
Host(`example.com`) && PathPrefix(`/api`)
|
|
Headers(`X-Custom`, `value`)
|
|
Method(`GET`, `POST`)
|
|
HostRegexp(`{subdomain:.+}.example.com`)
|
|
```
|
|
|
|
---
|
|
|
|
## Services
|
|
|
|
Services configure how to reach backend servers. Each service has a load balancer.
|
|
|
|
```yaml
|
|
http:
|
|
services:
|
|
my-service:
|
|
loadBalancer:
|
|
servers:
|
|
- url: "http://10.0.0.1:8080"
|
|
- url: "http://10.0.0.2:8080"
|
|
passHostHeader: true
|
|
sticky:
|
|
cookie:
|
|
name: traefik_lb
|
|
secure: true
|
|
httpOnly: true
|
|
```
|
|
|
|
Service types: **loadBalancer** (round-robin, weighted, mirroring, failover).
|
|
|
|
---
|
|
|
|
## Middlewares
|
|
|
|
Middlewares modify requests/responses before forwarding. Applied in declared order on routers, **and** can be attached to entrypoints (applied before router-level middleware).
|
|
|
|
### Available HTTP Middlewares (OSS)
|
|
|
|
| Middleware | Purpose |
|
|
|-----------|---------|
|
|
| **AddPrefix** | Add path prefix |
|
|
| **StripPrefix** | Strip path prefix |
|
|
| **StripPrefixRegex** | Strip path prefix via regex |
|
|
| **ReplacePath** | Replace request path |
|
|
| **ReplacePathRegex** | Replace path via regex |
|
|
| **RedirectRegex** | Redirect based on regex match |
|
|
| **RedirectScheme** | Redirect to different scheme (HTTP→HTTPS) |
|
|
| **Headers** | Add/remove/modify request/response headers |
|
|
| **BasicAuth** | HTTP Basic Authentication |
|
|
| **DigestAuth** | HTTP Digest Authentication |
|
|
| **ForwardAuth** | Delegate auth to external service |
|
|
| **RateLimit** | Rate limiting per source IP |
|
|
| **InFlightReq** | Limit concurrent requests |
|
|
| **CircuitBreaker** | Circuit breaker pattern |
|
|
| **Retry** | Retry failed requests |
|
|
| **Compress** | Gzip compression |
|
|
| **Buffering** | Buffer request/response |
|
|
| **Errors** | Custom error pages |
|
|
| **IPAllowList** | IP whitelist/blacklist |
|
|
| **ContentType** | Content-Type validation |
|
|
| **PassTLSClientCert** | Pass client certificate info in headers |
|
|
| **GrpcWeb** | gRPC-Web support |
|
|
| **Chain** | Combine multiple middlewares |
|
|
|
|
### Middleware Declaration (Docker Labels)
|
|
|
|
```yaml
|
|
labels:
|
|
# Declare middleware
|
|
- "traefik.http.middlewares.my-redirect.redirectscheme.scheme=https"
|
|
# Apply to router
|
|
- "traefik.http.routers.my-container.middlewares=my-redirect"
|
|
```
|
|
|
|
---
|
|
|
|
## Docker Provider
|
|
|
|
Traefik discovers Docker containers and creates routes from labels. Docker is a **first-class provider**.
|
|
|
|
### Enabling
|
|
|
|
```yaml
|
|
# In traefik.yml or CLI:
|
|
providers:
|
|
docker: {}
|
|
# CLI: --providers.docker=true
|
|
```
|
|
|
|
### Docker Provider Options
|
|
|
|
| Option | Description | Default |
|
|
|--------|-------------|---------|
|
|
| `endpoint` | Docker API endpoint | `unix:///var/run/docker.sock` |
|
|
| `exposedByDefault` | Expose all containers automatically | `true` |
|
|
| `network` | Default Docker network | — |
|
|
| `watch` | Watch Docker events | `true` |
|
|
| `defaultRule` | Default routing rule template | `Host({{ normalize .Name }})` |
|
|
| `constraints` | Filter which containers to route | — |
|
|
| `useBindPortIP` | Use bound port IP instead of inner network IP | `false` |
|
|
|
|
### Docker Label Examples
|
|
|
|
```yaml
|
|
services:
|
|
whoami:
|
|
image: traefik/whoami
|
|
labels:
|
|
- "traefik.enable=true"
|
|
- "traefik.http.routers.whoami.rule=Host(`whoami.localhost`)"
|
|
- "traefik.http.routers.whoami.entrypoints=websecure"
|
|
- "traefik.http.routers.whoami.tls=true"
|
|
```
|
|
|
|
#### Custom Container Port
|
|
|
|
```yaml
|
|
labels:
|
|
- "traefik.http.routers.my-container.rule=Host(`example.com`)"
|
|
- "traefik.http.services.my-service.loadbalancer.server.port=12345"
|
|
```
|
|
|
|
#### Multiple Routers per Container
|
|
|
|
```yaml
|
|
labels:
|
|
- "traefik.http.routers.www-router.rule=Host(`example-a.com`)"
|
|
- "traefik.http.routers.www-router.service=www-service"
|
|
- "traefik.http.services.www-service.loadbalancer.server.port=8000"
|
|
- "traefik.http.routers.admin-router.rule=Host(`example-b.com`)"
|
|
- "traefik.http.routers.admin-router.service=admin-service"
|
|
- "traefik.http.services.admin-service.loadbalancer.server.port=9000"
|
|
```
|
|
|
|
#### TCP Routing
|
|
|
|
```yaml
|
|
labels:
|
|
- "traefik.tcp.routers.my-router.rule=HostSNI(`example.com`)"
|
|
- "traefik.tcp.routers.my-router.tls=true"
|
|
- "traefik.tcp.services.my-service.loadbalancer.server.port=4123"
|
|
```
|
|
|
|
#### UDP Routing
|
|
|
|
```yaml
|
|
labels:
|
|
- "traefik.udp.routers.my-router.entrypoints=udp"
|
|
- "traefik.udp.services.my-service.loadbalancer.server.port=4123"
|
|
```
|
|
|
|
### Automatic Service Assignment
|
|
|
|
1. If a router rule is defined and a service port is set, but router doesn't specify a service → service auto-assigned.
|
|
2. If only a router rule is defined with no service at all → service auto-created and assigned.
|
|
3. If router explicitly names a service → that service is used.
|
|
|
|
---
|
|
|
|
## TLS
|
|
|
|
### Per-Router TLS
|
|
|
|
```yaml
|
|
http:
|
|
routers:
|
|
my-router:
|
|
rule: "Host(`example.com`)"
|
|
tls:
|
|
certResolver: "letsencrypt"
|
|
```
|
|
|
|
### Certificate Resolvers (ACME / Let's Encrypt)
|
|
|
|
```yaml
|
|
certificatesResolvers:
|
|
le:
|
|
acme:
|
|
email: "admin@example.com"
|
|
storage: "/letsencrypt/acme.json"
|
|
httpChallenge:
|
|
entryPoint: web
|
|
# dnsChallenge:
|
|
# provider: your-dns-provider
|
|
```
|
|
|
|
### Entrypoint-Level Default TLS
|
|
|
|
```yaml
|
|
entryPoints:
|
|
websecure:
|
|
address: ":443"
|
|
http:
|
|
tls:
|
|
certResolver: "le"
|
|
```
|
|
|
|
### ACME Challenge Types
|
|
|
|
- **HTTP-01**: Uses port 80 entrypoint (most common)
|
|
- **DNS-01**: Uses DNS TXT records (wildcard certs, no exposed port needed)
|
|
- **TLS-ALPN-01**: Uses port 443 entrypoint
|
|
|
|
---
|
|
|
|
## Observability
|
|
|
|
### Access Logs
|
|
|
|
```yaml
|
|
accessLog:
|
|
filePath: "/path/to/access.log"
|
|
format: json # json | common
|
|
filters:
|
|
statusCodes: "400-599"
|
|
minDuration: "10ms"
|
|
retryAttempts: true
|
|
```
|
|
|
|
### Metrics
|
|
|
|
```yaml
|
|
metrics:
|
|
prometheus:
|
|
entryPoint: metrics
|
|
addRoutersLabels: true
|
|
addServicesLabels: true
|
|
otlp:
|
|
grpc:
|
|
endpoint: "localhost:4317"
|
|
```
|
|
|
|
Supported exporters: **Prometheus**, **Datadog**, **StatsD**, **InfluxDB v2**, **OpenTelemetry (OTLP)**.
|
|
|
|
### Tracing
|
|
|
|
```yaml
|
|
tracing:
|
|
otlp:
|
|
grpc:
|
|
endpoint: "otel-collector:4317"
|
|
http:
|
|
endpoint: "otel-collector:4318"
|
|
```
|
|
|
|
### Per-Component Observability Override
|
|
|
|
All three (access logs, metrics, tracing) can be disabled/enabled per entrypoint or per router:
|
|
|
|
```yaml
|
|
entryPoints:
|
|
web:
|
|
observability:
|
|
accessLogs: false
|
|
metrics: false
|
|
tracing: false
|
|
```
|
|
|
|
---
|
|
|
|
## Complete Docker Setup Example
|
|
|
|
```yaml
|
|
services:
|
|
traefik:
|
|
image: traefik:v3.6
|
|
container_name: traefik
|
|
restart: unless-stopped
|
|
security_opt:
|
|
- no-new-privileges:true
|
|
networks:
|
|
- proxy
|
|
ports:
|
|
- "80:80"
|
|
- "443:443"
|
|
volumes:
|
|
- /var/run/docker.sock:/var/run/docker.sock:ro
|
|
- ./certs:/certs:ro
|
|
- ./dynamic:/dynamic:ro
|
|
command:
|
|
# Entrypoints
|
|
- "--entrypoints.web.address=:80"
|
|
- "--entrypoints.web.http.redirections.entrypoint.to=websecure"
|
|
- "--entrypoints.web.http.redirections.entrypoint.scheme=https"
|
|
- "--entrypoints.web.http.redirections.entrypoint.permanent=true"
|
|
- "--entrypoints.websecure.address=:443"
|
|
- "--entrypoints.websecure.http.tls=true"
|
|
# Providers
|
|
- "--providers.docker=true"
|
|
- "--providers.docker.exposedbydefault=false"
|
|
- "--providers.docker.network=proxy"
|
|
- "--providers.file.filename=/dynamic/tls.yaml"
|
|
# Dashboard (secured)
|
|
- "--api.dashboard=true"
|
|
- "--api.insecure=false"
|
|
# Observability
|
|
- "--log.level=INFO"
|
|
- "--accesslog=true"
|
|
- "--metrics.prometheus=true"
|
|
labels:
|
|
- "traefik.enable=true"
|
|
- "traefik.http.routers.dashboard.rule=Host(`dashboard.docker.localhost`)"
|
|
- "traefik.http.routers.dashboard.entrypoints=websecure"
|
|
- "traefik.http.routers.dashboard.service=api@internal"
|
|
- "traefik.http.routers.dashboard.tls=true"
|
|
- "traefik.http.middlewares.dashboard-auth.basicauth.users=<HASH>"
|
|
- "traefik.http.routers.dashboard.middlewares=dashboard-auth@docker"
|
|
```
|
|
|
|
---
|
|
|
|
## Supported Providers
|
|
|
|
| Provider | Type | Config Method |
|
|
|----------|------|--------------|
|
|
| Docker | Orchestrator | Labels |
|
|
| Kubernetes (CRD, Gateway API, Ingress) | Orchestrator | CRDs / Ingress |
|
|
| Docker Swarm | Orchestrator | Labels |
|
|
| Consul / Consul Catalog | Service Registry | KV tags |
|
|
| Nomad | Orchestrator | Tags |
|
|
| Redis / etcd / ZooKeeper / Consul (KV) | KV Store | Keys |
|
|
| File | Config File | YAML/TOML |
|
|
| HTTP | REST API | JSON/YAML |
|
|
| AWS ECS | Cloud | Labels |
|
|
|
|
---
|
|
|
|
## Key CLI Reference
|
|
|
|
```bash
|
|
# Run with Docker
|
|
docker run -d -p 80:80 -p 443:443 \
|
|
-v /var/run/docker.sock:/var/run/docker.sock \
|
|
-v $PWD/traefik.yml:/etc/traefik/traefik.yml \
|
|
traefik:v3.6
|
|
|
|
# Help
|
|
traefik --help
|
|
|
|
# Override config file
|
|
traefik --configFile=foo/bar/myconfigfile.yml
|
|
``` |