TL;DR — Resumen Rápido

Guía completa de middlewares de Traefik: enrutamiento HTTP, límite de tasa, cabeceras de seguridad, autenticación y circuit breakers para producción.

Middlewares de Traefik: Enrutamiento HTTP, Límite de Tasa y Seguridad

Los middlewares de Traefik son el mecanismo central para transformar solicitudes y respuestas HTTP entre el edge y tus servicios upstream. Tanto si necesitas aplicar límites de tasa, inyectar cabeceras de seguridad, eliminar prefijos de ruta o delegar la autenticación a un servicio externo, cada comportamiento es un objeto middleware discreto que adjuntas a un router. Esta guía cubre todas las categorías principales de middleware con ejemplos de configuración, una comparativa frente a alternativas y un ejemplo completo de Docker Compose para producción.

Requisitos Previos

  • Traefik v2.x o v3.x ejecutándose como contenedor Docker o en un host
  • Familiaridad básica con etiquetas de Docker Compose
  • Un dominio registrado con DNS apuntando a tu servidor
  • Opcional: Authelia u OAuth2-Proxy para flujos ForwardAuth

Arquitectura de Traefik: El Pipeline de Solicitudes

Traefik organiza el tráfico mediante cuatro primitivas:

  • Entrypoints — puertos de red donde llega el tráfico (:80, :443)
  • Routers — coinciden las solicitudes entrantes por host, ruta o cabeceras y las dirigen a un servicio
  • Middlewares — transforman la solicitud o respuesta (o la rechazan) antes de llegar al servicio
  • Services — los contenedores o servidores upstream que reciben la solicitud final

Traefik descubre estos objetos automáticamente desde etiquetas Docker, proveedores de ficheros (traefik.yml o dynamic/) o CRDs de Kubernetes (IngressRoute, Middleware).

Proveedores de Configuración de Middleware

Etiquetas Docker

labels:
  - "traefik.http.middlewares.mis-cabeceras.headers.stsSeconds=31536000"
  - "traefik.http.routers.miapp.middlewares=mis-cabeceras"

Proveedor de Ficheros (YAML dinámico)

# dynamic/middlewares.yml
http:
  middlewares:
    mis-cabeceras:
      headers:
        stsSeconds: 31536000
        stsIncludeSubdomains: true

CRD de Kubernetes

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: mis-cabeceras
spec:
  headers:
    stsSeconds: 31536000

Middleware de Cabeceras de Seguridad

El middleware Headers inyecta o modifica cabeceras HTTP en ambas direcciones.

http:
  middlewares:
    cabeceras-seguras:
      headers:
        customRequestHeaders:
          X-Forwarded-Proto: "https"
        customResponseHeaders:
          X-Powered-By: ""
        stsSeconds: 31536000
        stsIncludeSubdomains: true
        stsPreload: true
        forceSTSHeader: true
        frameDeny: true
        contentTypeNosniff: true
        browserXssFilter: true
        referrerPolicy: "strict-origin-when-cross-origin"
        permissionsPolicy: "camera=(), microphone=(), geolocation=()"
        contentSecurityPolicy: "default-src 'self'; script-src 'self' 'unsafe-inline'"
        accessControlAllowOrigin: "https://ejemplo.com"

Establecer una cabecera con valor vacío la elimina de la respuesta.

Límite de Tasa

El middleware RateLimit limita la frecuencia con la que un cliente puede hacer solicitudes.

http:
  middlewares:
    limite-api:
      rateLimit:
        average: 100
        burst: 50
        period: 1m
        sourceCriterion:
          requestHeaderName: "X-API-Key"
  • average — solicitudes sostenidas permitidas por period
  • burst — pico máximo por encima del promedio
  • period — ventana deslizante (por defecto 1s; admite 1m, 1h)
  • sourceCriterion — identifica al “cliente” por cabecera, host o estrategia de IP

Para despliegues detrás de una CDN, usa ipStrategy.depth: 1 para que Traefik utilice la IP real del cliente.

BasicAuth y DigestAuth

Protege rutas con autenticación HTTP cuando no hay SSO disponible.

http:
  middlewares:
    auth-basica:
      basicAuth:
        users:
          - "admin:$apr1$xyz$hashedpassword"
        usersFile: "/etc/traefik/.htpasswd"
        realm: "Área de Administración"
        removeHeader: true

Genera hashes con:

htpasswd -nb admin micontrasena

removeHeader: true elimina la cabecera Authorization antes del reenvío para evitar fugas de credenciales.

ForwardAuth: Integración SSO y OAuth2

ForwardAuth delega la decisión de autenticación a un servicio externo como Authelia u OAuth2-Proxy.

http:
  middlewares:
    auth-sso:
      forwardAuth:
        address: "http://authelia:9091/api/verify"
        trustForwardHeader: true
        authResponseHeaders:
          - "Remote-User"
          - "Remote-Groups"
          - "Remote-Email"

Traefik envía cada solicitud entrante a address primero. Si devuelve 2xx, la solicitud original continúa. Cualquier otro código se devuelve al cliente tal cual.

Middlewares de Manipulación de Rutas

StripPrefix

Elimina un prefijo antes de reenviar, útil cuando el upstream espera una ruta raíz.

http:
  middlewares:
    strip-api:
      stripPrefix:
        prefixes:
          - "/api/v1"
        forceSlash: true

Una solicitud a /api/v1/usuarios llega como /usuarios al upstream.

AddPrefix

Añade un prefijo. Útil cuando varias rutas apuntan al mismo servicio.

http:
  middlewares:
    agregar-v2:
      addPrefix:
        prefix: "/v2"

ReplacePath y ReplacePathRegex

http:
  middlewares:
    redireccion-legacy:
      replacePathRegex:
        regex: "^/antiguo/(.*)"
        replacement: "/nuevo/$1"

Compresión

http:
  middlewares:
    comprimir:
      compress:
        excludedContentTypes:
          - "image/jpeg"
          - "image/png"
        minResponseBodyBytes: 1024

Traefik admite gzip y brotli. Brotli se usa cuando el cliente envía Accept-Encoding: br.

Retry y CircuitBreaker

Retry

http:
  middlewares:
    reintentar:
      retry:
        attempts: 3
        initialInterval: "100ms"

CircuitBreaker

http:
  middlewares:
    circuit-breaker:
      circuitBreaker:
        expression: "ResponseCodeRatio(500, 600, 0, 600) > 0.30"
        checkPeriod: "10s"
        fallbackDuration: "30s"
        recoveryDuration: "10s"

El circuito se abre cuando expression es verdadera, bloqueando el tráfico durante fallbackDuration.

IPAllowList

Restringe el acceso a rangos de IP permitidos.

http:
  middlewares:
    solo-interno:
      ipAllowList:
        sourceRange:
          - "10.0.0.0/8"
          - "172.16.0.0/12"
          - "192.168.0.0/16"
        ipStrategy:
          depth: 2

Middlewares de Redirección

RedirectScheme (HTTP → HTTPS)

http:
  middlewares:
    redireccion-https:
      redirectScheme:
        scheme: "https"
        permanent: true

RedirectRegex (www → sin www)

http:
  middlewares:
    redireccion-www:
      redirectRegex:
        regex: "^https://www\\.(.+)"
        replacement: "https://${1}"
        permanent: true

Cadenas de Middlewares

Las cadenas permiten componer múltiples middlewares en un único pipeline con nombre.

http:
  middlewares:
    stack-seguro:
      chain:
        middlewares:
          - cabeceras-seguras
          - redireccion-https
          - limite-api
          - auth-sso

Adjunta la cadena a un router con una sola etiqueta:

labels:
  - "traefik.http.routers.miapp.middlewares=stack-seguro"

Comparativa: Traefik vs Alternativas

FunciónTraefikNginx (módulos)Envoy (filtros)Kong (plugins)Caddy (handlers)
Límite de tasaIntegradolimit_reqratelimit filterPlugin oficialrate_limit
Delegación de authForwardAuthauth_requestext_authzPlugin OIDCforward_auth
Circuit breakerIntegradoNo nativoIntegradoRequiere pluginNo nativo
Reescritura de rutaIntegradorewriterewrite filterIntegradorewrite
CompresiónIntegradomódulo gzipcompressorNo nativoIntegrado
Config dinámicaAuto (labels/CRD)Requiere reloadxDS APIAdmin APIAuto (Caddyfile)

Ejemplo Completo de Docker Compose para Producción

Tienes un servicio API en producción que necesita HTTPS, límite de tasa, cabeceras de seguridad y BasicAuth en la ruta de administración.

services:
  traefik:
    image: traefik:v3.1
    restart: unless-stopped
    command:
      - --providers.docker=true
      - --providers.docker.exposedbydefault=false
      - --providers.file.directory=/etc/traefik/dynamic
      - --entrypoints.web.address=:80
      - --entrypoints.web.http.redirections.entryPoint.to=websecure
      - --entrypoints.web.http.redirections.entryPoint.scheme=https
      - --entrypoints.websecure.address=:443
      - --certificatesresolvers.le.acme.email=ops@ejemplo.com
      - --certificatesresolvers.le.acme.storage=/letsencrypt/acme.json
      - --certificatesresolvers.le.acme.tlschallenge=true
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt
      - ./dynamic:/etc/traefik/dynamic:ro
    networks:
      - edge

  api:
    image: ghcr.io/ejemplo/api:latest
    restart: unless-stopped
    networks:
      - edge
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.api.rule=Host(`api.ejemplo.com`)"
      - "traefik.http.routers.api.entrypoints=websecure"
      - "traefik.http.routers.api.tls.certresolver=le"
      - "traefik.http.routers.api.middlewares=stack-seguro"
      - "traefik.http.services.api.loadbalancer.server.port=8080"
      - "traefik.http.middlewares.hdrs.headers.stsSeconds=31536000"
      - "traefik.http.middlewares.hdrs.headers.frameDeny=true"
      - "traefik.http.middlewares.rl.rateLimit.average=120"
      - "traefik.http.middlewares.rl.rateLimit.burst=40"
      - "traefik.http.middlewares.rl.rateLimit.period=1m"
      - "traefik.http.middlewares.compress.compress=true"
      - "traefik.http.middlewares.stack-seguro.chain.middlewares=hdrs,rl,compress"

networks:
  edge:
    external: true

Errores Comunes y Casos Límite

  • Signos de dólar en hashes de BasicAuth deben duplicarse ($$) en etiquetas Docker porque Docker Compose interpola $ como variable.
  • El orden de middlewares en una cadena es importante. Aplica redirecciones antes que autenticación; aplica compresión al final.
  • La latencia de ForwardAuth añade un round-trip extra por solicitud. Usa caché de decisiones en Authelia u OAuth2-Proxy.
  • Los contadores de RateLimit son por réplica. Con tres réplicas de Traefik la tasa permitida se multiplica por tres.
  • CircuitBreaker usa su propio lenguaje de expresiones, no PromQL. Consulta la documentación oficial para ResponseCodeRatio y LatencyAtQuantileMS.

Resumen

  • Los middlewares de Traefik se adjuntan a routers y transforman solicitudes antes de llegar a los servicios upstream
  • Usa Headers para HSTS, CSP y CORS; elimina siempre cabeceras sensibles hacia el upstream
  • RateLimit con sourceCriterion gestiona la limitación de APIs; configura ipStrategy.depth detrás de CDNs
  • ForwardAuth integra Authelia y OAuth2-Proxy para SSO sin modificar el código de la aplicación
  • StripPrefix, ReplacePath y AddPrefix normalizan rutas para enrutamiento multi-tenant
  • CircuitBreaker y Retry aportan resiliencia upstream; combínalos con Buffering para protección ante cargas lentas
  • Las cadenas Chain componen pipelines de seguridad reutilizables adjuntables a cualquier router con una etiqueta

Artículos Relacionados