From da69ead827b549ac06243c6cf5dd3cc1af3a101d Mon Sep 17 00:00:00 2001 From: Atlas Date: Wed, 15 Apr 2026 11:16:04 -0700 Subject: [PATCH] Create: reference/traefik.md --- reference/traefik.md | 571 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 571 insertions(+) create mode 100644 reference/traefik.md diff --git a/reference/traefik.md b/reference/traefik.md new file mode 100644 index 0000000..2575694 --- /dev/null +++ b/reference/traefik.md @@ -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=" + - "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 +``` \ No newline at end of file