vh/VuongKB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Create: reference/traefik.md

Browse Source
This commit is contained in:
Atlas
2026-04-15 11:16:04 -07:00
parent 991848f871
commit da69ead827
1 changed files with 571 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
reference/traefik.md
+571
View File
@@ -0,0 +1,571 @@
---
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
```