Traefik Cheat Sheet

Router Rules

Rules live on routers, in a label or a dynamic config file. Values go in backticks, never quotes. Combine matchers with && (and), || (or), ! (not), and parentheses.

When two routers both match, the longer rule string wins. Override with traefik.http.routers.<name>.priority=10 (higher wins).

v2 differences: HostRegexp used {name:regex} placeholders instead of plain regex, the matchers were Headers() and HeadersRegexp() (plural), and Host()/PathPrefix() accepted comma-separated values. In v3 chain them with ||.

Docker Labels

Labels on the app container, not on Traefik. The Traefik label generator builds these interactively.

A working docker compose setup:

services:
  traefik:
    image: traefik:v3
    command:
      - --providers.docker=true
      - --providers.docker.exposedbydefault=false
      - --entrypoints.web.address=:80
      - --entrypoints.websecure.address=:443
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro

  app:
    image: myapp:latest
    labels:
      - traefik.enable=true
      - traefik.http.routers.app.rule=Host(`app.example.com`)
      - traefik.http.routers.app.entrypoints=websecure
      - traefik.http.routers.app.tls.certresolver=letsencrypt
      - traefik.http.services.app.loadbalancer.server.port=3000

The router name (app here) is arbitrary; it just has to be the same across that container's labels.

Static vs Dynamic Config

Static config is read once at startup: entrypoints, providers, certificate resolvers, logging. It comes from traefik.yml (looked up in /etc/traefik/), CLI flags, or TRAEFIK_* environment variables; pick one style. Dynamic config is routers, services, and middlewares; it comes from labels or watched files and applies without a restart.

# /etc/traefik/traefik.yml (static)
entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

providers:
  docker:
    exposedByDefault: false
  file:
    directory: /etc/traefik/dynamic
    watch: true

api:
  dashboard: true

A dynamic file routes to things that are not containers, like a service on the host:

# /etc/traefik/dynamic/api.yml
http:
  routers:
    api:
      rule: Host(`api.example.com`)
      entryPoints: [websecure]
      service: api
      tls:
        certResolver: letsencrypt
  services:
    api:
      loadBalancer:
        servers:
          - url: http://192.168.1.10:3000

Changing a dynamic file or a label applies immediately. Changing traefik.yml needs a container restart.

EntryPoints

EntryPoints are the ports Traefik listens on. The names web and websecure are convention, not built in.

Behind Cloudflare or another proxy, the client IP arrives in X-Forwarded-For and Traefik ignores it until that proxy's ranges are in forwardedheaders.trustedips. Without that, ClientIP rules, ipallowlist, and rate limits all see the proxy instead of the visitor.

Redirect all HTTP to HTTPS at the entrypoint, so no per-container labels are needed:

entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https

Middlewares

Define a middleware once, attach it to any router with traefik.http.routers.<router>.middlewares=<name>. Reference one from another provider with a suffix: auth@file, auth@docker, auth@kubernetescrd.

In a compose file every $ in a basicauth hash or a regex replacement must be doubled to $$ or compose eats it as a variable.

Let's Encrypt

Certificate resolvers are static config. Traefik requests and renews certificates on its own and stores them in acme.json.

certificatesResolvers:
  letsencrypt:
    acme:
      email: [email protected]
      storage: /letsencrypt/acme.json
      httpChallenge:
        entryPoint: web

A wildcard from Cloudflare needs the DNS challenge in static config and an API token in the environment:

certificatesResolvers:
  letsencrypt:
    acme:
      email: [email protected]
      storage: /letsencrypt/acme.json
      dnsChallenge:
        provider: cloudflare
        resolvers:
          - "1.1.1.1:53"

# same compose service
environment:
  - CF_DNS_API_TOKEN=...   # needs Zone:Read and DNS:Edit on that zone
labels:
  - traefik.http.routers.app.tls.certresolver=letsencrypt
  - traefik.http.routers.app.tls.domains[0].main=example.com
  - traefik.http.routers.app.tls.domains[0].sans=*.example.com

Let's Encrypt limits issuance to 5 duplicate certificates a week, so keep acme.json in a volume and use the staging CA while testing. "Could not find zone for domain" means the token cannot read that zone, or the apex is delegated to different nameservers than the one you asked for.

TCP & UDP

Non-HTTP services get their own router type on their own entrypoint. TCP rules match on SNI, not on paths or headers.

Protocols without SNI (SSH, Postgres, plain MQTT) can only use HostSNI(`*`), and one entrypoint holds one such router. Give each backend its own port. With tls.passthrough=true Traefik never decrypts, so no middleware or certificate resolver applies to that router.

Kubernetes

Traefik ships as an ingress controller. It reads plain Ingress objects, its own IngressRoute CRDs, and the Gateway API. k3s installs it by default.

apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: app
spec:
  entryPoints: [websecure]
  routes:
    - match: Host(`app.example.com`) && PathPrefix(`/`)
      kind: Rule
      middlewares:
        - name: strip
      services:
        - name: app
          port: 3000
  tls:
    certResolver: letsencrypt

Annotations do the same job on a plain Ingress:

metadata:
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.tls: "true"
    traefik.ingress.kubernetes.io/router.middlewares: default-strip@kubernetescrd

The CRD API group is traefik.io/v1alpha1 in v3 and traefik.containo.us/v1alpha1 in v2; applying v2 manifests to a v3 install fails with "no matches for kind". A middleware in another namespace needs that namespace in the reference and providers.kubernetesCRD.allowCrossNamespace=true.

Plugins

Plugins are declared in static config, downloaded from plugins.traefik.io at startup, and run as interpreted Go, so no rebuild is involved. Once declared, a plugin is used like any other middleware.

# static config
experimental:
  plugins:
    bouncer:
      moduleName: github.com/maxlerebourg/crowdsec-bouncer-traefik-plugin
      version: v1.4.5

Plugins load only at startup, so adding one means restarting Traefik, not just editing a label.

CLI & Flags

The binary has two subcommands; everything else is flags. Every flag maps to a static config key and to a TRAEFIK_* environment variable.

Logs & Metrics

Two separate logs. The Traefik log is about Traefik; the access log is about requests. Both go to stdout unless given a path.

Access logs written to a file inside the container disappear on recreate unless the path is on a volume. docker compose logs traefik only shows what went to stdout.

Healthcheck

Two different things share the name: checking Traefik itself, and Traefik checking your backends.

When a backend fails its check, Traefik takes it out of rotation until it passes again; with one replica that means 404s, so backend healthchecks matter most with multiple replicas.

Dashboard & API

The dashboard shows every router, service, and middleware, and flags configuration errors that logs bury.

Never ship api.insecure=true on a public host; the dashboard reveals every internal hostname and middleware secret name.

Running & Debugging

Traefik runs as a container, so day-to-day operation is docker compose. The docker compose cheat sheet covers the rest.

More container commands are on the docker cheat sheet.

v2 to v3

Most setups move over untouched. These are the renames that stop a container from starting or silently drop a route.

Run the old config against v3 with --log.level=DEBUG in a throwaway container first; unknown keys are reported by name at startup.

Gotchas

• Rules use backticks around values. Quotes inside Host("...") fail silently in some setups and loudly in others; backticks always work.
• Set exposedByDefault: false. Without it every container on the socket gets routed, including ones you never meant to publish.
• A 404 from Traefik usually means no router matched (wrong Host, wrong entrypoint); a "Bad Gateway" means the router matched but Traefik cannot reach the container, almost always a network mismatch. Put both containers on one network or set traefik.docker.network.
• When a container exposes several ports, Traefik picks one arbitrarily. Pin it with loadbalancer.server.port.
• $ doubling in compose applies to basicauth hashes only in compose files, not in dynamic file config. The same hash needs $$ in a label and $ in a YAML file.
• If HTTPS works but keeps serving the "TRAEFIK DEFAULT CERT", the resolver failed; check the logs for acme errors and confirm port 80 (HTTP challenge) reaches Traefik.
• "Too many redirects" behind Cloudflare means Cloudflare SSL is set to Flexible while Traefik also redirects to HTTPS. Set Cloudflare to Full (strict).
• Upgrading v2 to v3 mostly just works, but HostRegexp placeholder rules, Headers() matchers, and ipWhiteList middlewares need renaming first.