vh/VuongKB

Fork 0

Files

T

Atlas da69ead827 Create: reference/traefik.md

2026-04-15 11:16:04 -07:00

16 KiB

Raw Blame History

created, id, keywords, links, modified, summary, tags, title

created

keywords

links

modified

summary

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

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

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.

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)

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

# 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

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

labels:
  - "traefik.http.routers.my-container.rule=Host(`example.com`)"
  - "traefik.http.services.my-service.loadbalancer.server.port=12345"

Multiple Routers per Container

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

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

labels:
  - "traefik.udp.routers.my-router.entrypoints=udp"
  - "traefik.udp.services.my-service.loadbalancer.server.port=4123"

Automatic Service Assignment

If a router rule is defined and a service port is set, but router doesn't specify a service → service auto-assigned.
If only a router rule is defined with no service at all → service auto-created and assigned.
If router explicitly names a service → that service is used.

TLS

Per-Router TLS

http:
  routers:
    my-router:
      rule: "Host(`example.com`)"
      tls:
        certResolver: "letsencrypt"

Certificate Resolvers (ACME / Let's Encrypt)

certificatesResolvers:
  le:
    acme:
      email: "admin@example.com"
      storage: "/letsencrypt/acme.json"
      httpChallenge:
        entryPoint: web
      # dnsChallenge:
      #   provider: your-dns-provider

Entrypoint-Level Default TLS

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

accessLog:
  filePath: "/path/to/access.log"
  format: json           # json | common
  filters:
    statusCodes: "400-599"
    minDuration: "10ms"
    retryAttempts: true

Metrics

metrics:
  prometheus:
    entryPoint: metrics
    addRoutersLabels: true
    addServicesLabels: true
  otlp:
    grpc:
      endpoint: "localhost:4317"

Supported exporters: Prometheus, Datadog, StatsD, InfluxDB v2, OpenTelemetry (OTLP).

Tracing

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:

entryPoints:
  web:
    observability:
      accessLogs: false
      metrics: false
      tracing: false

Complete Docker Setup Example

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

# 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

16 KiB Raw Blame History