Plugins en Traefik

Los middlewares que vienen con Traefik cubren la mayoría de los casos de uso, pero a veces necesitas algo más específico. Algo que no viene de serie. Para eso están los plugins. Traefik v3 tiene un sistema de plugins que te permite extender su funcionalidad más allá de lo que ofrecen los middlewares nativos. Hay plugins para geolocalización, para integrar con servicios externos, para modificar cabeceras de formas más avanzadas, para reescribir cuerpos de peticiones, y un largo etcétera.

Si has seguido el tutorial hasta aquí, ya sabes manejar routers, entrypoints, middlewares básicos y configuración dinámica. Los plugins son el siguiente nivel. Te permiten hacer cosas que con los middlewares de serie no puedes, o tendrías que hacer de forma mucho más complicada.

¿Qué son los plugins de Traefik?

Los plugins son pequeños programas que se ejecutan dentro de Traefik y que actúan como middlewares. Se escriben en Go y se compilan a WebAssembly (WASM), lo que los hace seguros y rápidos. Al ejecutarse en un sandbox de WASM, un plugin no puede acceder al sistema de archivos del host ni a recursos del sistema que no le correspondan. Esto te da tranquilidad: aunque el plugin tenga un bug, no va a comprometer tu servidor.

Desde Traefik v3, los plugins son nativos. Ya no necesitas flags experimentales ni configuraciones especiales. Bueno, casi nativos: todavía tienes que declararlos bajo la sección experimental en la configuración estática, pero no necesitas activar nada adicional. Es simplemente el nombre de la sección donde se declaran.

El flujo es sencillo:

1. Declaras el plugin en la configuración estática (traefik.yml), indicando su módulo y versión.
2. Configuras el middleware con los parámetros del plugin en la configuración dinámica.
3. Asocias ese middleware a uno o varios routers.

Y Traefik se encarga del resto: descarga el plugin, lo compila a WASM si es necesario, y lo ejecuta en el sandbox.

Dónde encontrar plugins

El catálogo oficial de plugins está en plugins.traefik.io. Allí encontrarás plugins para,

• Geobloqueo: bloquear tráfico por país con distintos niveles de granularidad.
• Modificación de cabeceras: más avanzado que el middleware Headers estándar, con capacidad de transformar valores dinámicamente.
• Integración con servicios: CrowdSec, fail2ban, Coraza WAF, etc.
• Transformación de peticiones: modificar el cuerpo de la petición o la respuesta sobre la marcha.
• Redirecciones avanzadas: más allá del middleware redirectRegex de serie.
• Autenticación: plugins para integrar con OAuth2, OIDC, Authelia, Vouch, etc.
• Rate limiting avanzado: con lógicas más complejas que el RateLimit nativo.
• Y muchos más.

Cada plugin en el catálogo tiene su propia página con documentación, ejemplos de configuración y enlace al repositorio de GitHub. Antes de instalar un plugin, te recomiendo que le eches un vistazo a la documentación para asegurarte de que hace exactamente lo que necesitas. También puedes ver las issues abiertas en GitHub para saber si tiene bugs conocidos o limitaciones.

Además del catálogo oficial, hay plugins que no están listados pero que funcionan igualmente. Mientras el módulo sea accesible desde GitHub y tenga el formato correcto, Traefik lo descargará y ejecutará sin problema. Pero te recomiendo que te ciñas al catálogo oficial siempre que puedas, porque los plugins listados han pasado un proceso de revisión básico.

Configurar un plugin

Los plugins se configuran en dos pasos: primero los declaras en la configuración estática y luego los usas como middlewares en la configuración dinámica.

1. Declarar el plugin en traefik.yml

experimental:
  plugins:
    geoblock:
      moduleName: github.com/Paxxs/geoblock
      version: v0.3.0

• moduleName: la ruta del módulo en GitHub. Debe ser la ruta completa del repositorio.
• version: la versión del plugin, usando etiquetas de Git (tags). Normalmente son versiones semánticas como v0.3.0.

Puedes declarar tantos plugins como necesites. Cada uno con su propio nombre, módulo y versión.

experimental:
  plugins:
    geoblock:
      moduleName: github.com/Paxxs/geoblock
      version: v0.3.0
    crowdsec:
      moduleName: github.com/crowdsecurity/cs-traefik-bouncer
      version: v0.1.0
    real-ip:
      moduleName: github.com/BetterCorp/real-ip
      version: v1.0.0

Cuando Traefik arranca, descarga cada plugin, lo compila a WASM y lo deja listo para usar. Si alguno falla, lo verás en los logs con un mensaje claro.

2. Configurar el middleware en un archivo dinámico

Una vez declarado el plugin, lo configuras como un middleware más en tu configuración dinámica.

http:
  middlewares:
    geoblock-europa:
      plugin:
        geoblock:
          allowLocal: true
          allowedCountries:
            - "ES"
            - "FR"
            - "DE"
            - "IT"
            - "PT"
          api: "https://api.geo.ipify.org"

Fíjate en la estructura: bajo plugin pones el nombre que le diste al declararlo (en este caso geoblock), y dentro los parámetros que acepta ese plugin en concreto. Cada plugin tiene sus propios parámetros, así que tendrás que consultar su documentación.

3. Usarlo en un router

Desde el File provider,

http:
  routers:
    mi-app:
      rule: Host(`app.dominio.com`)
      middlewares:
        - geoblock-europa@file

O desde las labels de Docker,

labels:
  - "traefik.http.routers.mi-app.middlewares=geoblock-europa@file"

Y ya está. A partir de ese momento, todas las peticiones que lleguen a app.dominio.com pasarán por el plugin de geobloqueo antes de llegar a tu servicio.

Plugin de geobloqueo

El plugin de geobloqueo es uno de los más populares, y con razón. Te permite restringir el acceso a tu servicio según el país de origen del cliente. Esto te puede ahorrar más de un disgusto si, por ejemplo, tienes un servicio que solo debe estar disponible en España, o quieres bloquear tráfico de países desde los que recibes ataques constantemente.

Configuración básica

# traefik.yml - Configuración estática
experimental:
  plugins:
    geoblock:
      moduleName: github.com/Paxxs/geoblock
      version: v0.3.0

# dynamic/plugins.yml - Configuración dinámica
http:
  middlewares:
    solo-espana:
      plugin:
        geoblock:
          allowLocal: true
          allowedCountries:
            - "ES"
          api: "https://api.geo.ipify.org"
          cacheSize: 100
          forceMatch: false

Y lo aplicas a un router,

  - "traefik.http.routers.mi-app.middlewares=solo-espana@file"

Modo whitelist vs blacklist

El plugin geoblock soporta dos modos de funcionamiento. En el ejemplo anterior estás usando whitelist: solo permites los países que listas. Pero también puedes configurarlo en modo blacklist, bloqueando solo los países que quieras excluir.

http:
  middlewares:
    bloquea-rusos:
      plugin:
        geoblock:
          allowLocal: true
          allowedCountries:
            - "ES"
            - "FR"
            - "DE"
            - "IT"
            - "PT"
            - "GB"
            - "US"
          blockedCountries:
            - "RU"
            - "CN"
            - "KP"
          api: "https://api.geo.ipify.org"
          cacheSize: 200
          forceMatch: true

Con forceMatch: true le dices al plugin que si no puede determinar la geolocalización de una IP, la bloquee. Esto es más restrictivo, pero también más seguro. Con forceMatch: false, si no puede determinar el país, permite el acceso. Esto te puede dar problemas de seguridad, así que te recomiendo que uses forceMatch: true en producción.

Configuración avanzada con múltiples middlewares

Puedes tener varios middlewares de geobloqueo para diferentes routers. Por ejemplo, un middleware para servicios públicos y otro más restrictivo para el panel de administración.

http:
  middlewares:
    acceso-publico:
      plugin:
        geoblock:
          allowLocal: true
          allowedCountries:
            - "ES"
            - "FR"
            - "DE"
            - "IT"
            - "PT"
            - "GB"
          api: "https://api.geo.ipify.org"
          cacheSize: 500
          forceMatch: false

    solo-admins:
      plugin:
        geoblock:
          allowLocal: true
          allowedCountries:
            - "ES"
          api: "https://api.geo.ipify.org"
          cacheSize: 50
          forceMatch: true

Luego asignas cada uno al router que corresponda,

http:
  routers:
    tienda:
      rule: Host(`tienda.dominio.com`)
      middlewares:
        - acceso-publico@file
      service: tienda-service

    admin:
      rule: Host(`admin.dominio.com`)
      middlewares:
        - solo-admins@file
        - auth-basic@file
      service: admin-service

API de geolocalización

El plugin necesita una API externa para resolver la geolocalización de las IPs. Por defecto usa https://api.geo.ipify.org, que es gratuita y no requiere registro. Pero tiene un límite de peticiones. Si tienes mucho tráfico, puedes toparte con rate limiting.

Algunas alternativas que puedes usar,

• ip-api.com: 45 peticiones por minuto gratis, sin necesidad de API key. Muy fiable.
• ipinfo.io: 50.000 peticiones al mes gratis, con registro.
• MaxMind GeoIP: si tienes tu propia base de datos GeoIP, puedes montar un servicio interno.

Si tu servicio recibe muchas peticiones, el parámetro cacheSize es tu mejor aliado. Cuanto más grande sea la caché, menos llamadas harás a la API externa. Con cacheSize: 1000 puedes cubrir la mayoría de los casos sin problemas.

http:
  middlewares:
    geoblock-global:
      plugin:
        geoblock:
          allowLocal: true
          allowedCountries:
            - "ES"
          api: "https://ip-api.com/json/"
          cacheSize: 1000
          forceMatch: true
          cacheTimeout: 86400

El parámetro cacheTimeout lo configuras en segundos. 86400 segundos son 24 horas. Las IPs de los usuarios normales no cambian de país a menudo, así que puedes poner una caché larga sin problema.

Ejemplo completo con Docker Compose

Te dejo un ejemplo completo funcionando, con todo lo necesario para levantar Traefik con geobloqueo y un servicio de prueba.

# traefik.yml
entryPoints:
  web:
    address: ":80"
    http:
      redirections:
        entryPoint:
          to: websecure
          scheme: https
  websecure:
    address: ":443"

providers:
  docker:
    endpoint: "unix:///var/run/docker.sock"
    exposedByDefault: false
  file:
    directory: /etc/traefik/dynamic
    watch: true

api:
  dashboard: true

certificatesResolvers:
  letsencrypt:
    acme:
      email: tu@email.com
      storage: /letsencrypt/acme.json
      httpChallenge:
        entryPoint: web

experimental:
  plugins:
    geoblock:
      moduleName: github.com/Paxxs/geoblock
      version: v0.3.0

# dynamic/plugins.yml
http:
  middlewares:
    solo-espana:
      plugin:
        geoblock:
          allowLocal: true
          allowedCountries:
            - "ES"
          api: "https://api.geo.ipify.org"
          cacheSize: 200
          forceMatch: true

# docker-compose.yml
services:
  traefik:
    image: traefik:v3.7
    container_name: traefik
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./traefik.yml:/etc/traefik/traefik.yml:ro
      - ./dynamic:/etc/traefik/dynamic:ro
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./letsencrypt:/letsencrypt
    networks:
      - traefik-net

  miapp:
    image: nginx:alpine
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.miapp.rule=Host(`app.dominio.com`)"
      - "traefik.http.routers.miapp.entrypoints=websecure"
      - "traefik.http.routers.miapp.tls=true"
      - "traefik.http.routers.miapp.middlewares=solo-espana@file"
    networks:
      - traefik-net

networks:
  traefik-net:
    external: true

Plugin de CrowdSec

CrowdSec es un sistema de detección de intrusiones colaborativo. Su plugin para Traefik te permite bloquear IPs maliciosas en tiempo real, basándose en la base de datos compartida de la comunidad CrowdSec. Si alguien intenta atacar tu servidor y ya ha sido reportado por otro usuario, la IP queda bloqueada automáticamente.

# traefik.yml
experimental:
  plugins:
    crowdsec:
      moduleName: github.com/crowdsecurity/cs-traefik-bouncer
      version: v0.1.0

# dynamic/plugins.yml
http:
  middlewares:
    crowdsec-bouncer:
      plugin:
        crowdsec:
          crowdsecLapiUrl: http://crowdsec:8080
          crowdsecLapiKey: TU_API_KEY
          crowdsecMode: "live"

Necesitarás tener CrowdSec corriendo en un contenedor aparte, pero eso lo veremos en el capítulo de seguridad. Lo interesante de este plugin es que no sustituye a otras medidas de seguridad, sino que se complementa. Puedes tener geobloqueo + CrowdSec + rate limiting funcionando a la vez.

El modo live significa que CrowdSec decide en tiempo real si bloquea o no. También existe el modo stream, donde CrowdSec te envía las decisiones de forma asíncrona. Para la mayoría de los casos, live es la opción correcta.

Plugin de fail2ban

Si vienes del mundo de Nginx o Apache, seguro que conoces fail2ban. Es esa herramienta que analiza los logs y bloquea IPs después de demasiados intentos fallidos. Pues existe un plugin para Traefik que hace exactamente eso.

experimental:
  plugins:
    fail2ban:
      moduleName: github.com/tomMoulard/fail2ban
      version: v0.3.0

http:
  middlewares:
    fail2ban-bouncer:
      plugin:
        fail2ban:
          redis:
            host: redis
            port: 6379
          banDuration: 3600
          findTime: 600
          maxRetry: 5

Este plugin necesita Redis para funcionar. Cada vez que una petición llega, el plugin comprueba si la IP de origen ha superado el límite de intentos fallidos en el periodo configurado. Si es así, la bloquea durante banDuration segundos.

• banDuration: tiempo de bloqueo en segundos. 3600 son 1 hora.
• findTime: ventana de tiempo en segundos para contar los intentos.
• maxRetry: número máximo de intentos antes del bloqueo.

Puedes combinarlo con el middleware de RateLimit para tener una defensa en capas: el RateLimit frena picos de tráfico, y fail2ban se encarga de los ataques sostenidos.

Plugin de modificación de cabeceras avanzado (real-ip)

El middleware headers de serie está bien para cosas básicas, pero el plugin real-ip te permite manejar la IP real del cliente de formas más avanzadas. Esto es especialmente útil cuando tienes Traefik detrás de un CDN como Cloudflare o CloudFront.

experimental:
  plugins:
    real-ip:
      moduleName: github.com/BetterCorp/real-ip
      version: v1.0.0

http:
  middlewares:
    real-ip-cloudflare:
      plugin:
        real-ip:
          trustedHosts:
            - "103.21.244.0/22"
            - "103.22.200.0/22"
            - "103.31.4.0/22"
            - "104.16.0.0/12"
            - "108.162.192.0/18"
            - "131.0.72.0/22"
            - "141.101.64.0/18"
            - "162.158.0.0/15"
            - "172.64.0.0/13"
            - "173.245.48.0/20"
            - "188.114.96.0/20"
            - "190.93.240.0/20"
            - "197.234.240.0/22"
            - "198.41.128.0/17"
          headers:
            - "CF-Connecting-IP"
            - "X-Forwarded-For"

Este plugin reemplaza la IP de origen por la que viene en las cabeceras de confianza, pero solo si la conexión proviene de una IP de la lista trustedHosts. Esto evita que un atacante pueda falsear la cabecera X-Forwarded-For desde fuera de Cloudflare.

Plugin de transformación de cuerpo (transform-body)

¿Necesitas modificar el cuerpo de una respuesta antes de que llegue al cliente? El plugin transform-body te permite hacer sustituciones, inyecciones y modificaciones sobre la marcha. Esto te puede ahorrar más de un disgusto si tienes un servicio que no puedes modificar pero necesitas cambiar algo en sus respuestas.

experimental:
  plugins:
    transform-body:
      moduleName: github.com/metalmatze/transform-body
      version: v0.1.0

http:
  middlewares:
    inject-header:
      plugin:
        transform-body:
          rules:
            - find: "</body>"
              replace: "<script src=\"https://cdn.mi-analytics.com/script.js\"></script></body>"

Este plugin busca un texto en el cuerpo de la respuesta y lo reemplaza por otro. Puedes tener múltiples reglas. Es útil para inyectar scripts de analytics, añadir avisos legales, o modificar contenido sin tocar el backend.

Eso sí, ten en cuenta que modificar el cuerpo de una respuesta tiene un coste de rendimiento. Para cada respuesta, Traefik tiene que leer el cuerpo completo, buscar y reemplazar, y luego enviarlo. Si tienes mucho tráfico, nota la diferencia. Úsalo solo cuando realmente lo necesites.

Plugin de CORS avanzado

El middleware headers de serie permite configurar CORS básico, pero si necesitas algo más flexible, el plugin traefik-cors te da control total.

experimental:
  plugins:
    cors:
      moduleName: github.com/hika05/traefik-cors
      version: v1.0.0

http:
  middlewares:
    cors-api:
      plugin:
        cors:
          allowOrigins:
            - "https://app.dominio.com"
            - "https://admin.dominio.com"
          allowMethods:
            - "GET"
            - "POST"
            - "PUT"
            - "DELETE"
            - "OPTIONS"
          allowHeaders:
            - "Authorization"
            - "Content-Type"
            - "X-Requested-With"
          allowCredentials: true
          maxAge: 86400

Con este plugin puedes definir orígenes permitidos con más precisión, métodos HTTP específicos, cabeceras personalizadas y el tiempo de caché para las peticiones OPTIONS. Es perfecto para APIs públicas o semi-públicas.

Integración con más servicios

Los plugins de Traefik no se limitan a geobloqueo y seguridad. También puedes integrar servicios externos directamente desde el proxy.

Coraza Web Application Firewall

Coraza es un WAF (Web Application Firewall) de código abierto compatible con las reglas de ModSecurity. Su plugin para Traefik te permite analizar las peticiones HTTP en busca de patrones maliciosos antes de que lleguen a tu aplicación.

experimental:
  plugins:
    coraza:
      moduleName: github.com/corazawaf/coraza-traefik
      version: v0.1.0

http:
  middlewares:
    waf-coraza:
      plugin:
        coraza:
          directives: |
            Include /etc/coraza/coreruleset/crs-setup.conf
            Include /etc/coraza/coreruleset/rules/*.conf

Con Coraza puedes detectar y bloquear SQL injection, XSS, path traversal, y un montón de ataques más. Las reglas de OWASP CRS (Core Rule Set) son el estándar de facto para WAFs.

Plugin de OAuth2 / OIDC

Si necesitas proteger tus servicios con autenticación delegada, hay plugins que integran OAuth2 y OpenID Connect directamente en Traefik. Por ejemplo, el plugin traefik-oidc de DicePress.

experimental:
  plugins:
    oidc:
      moduleName: github.com/dicepress/traefik-oidc
      version: v0.5.0

http:
  middlewares:
    auth-oidc:
      plugin:
        oidc:
          provider:
            url: "https://accounts.google.com"
            clientId: "TU_CLIENT_ID"
            clientSecret: "TU_CLIENT_SECRET"
          redirect:
            url: "https://app.dominio.com/callback"
          session:
            store: redis
            redis:
              host: redis
              port: 6379

Con este plugin, cualquier petición no autenticada se redirige al proveedor OIDC (Google, GitHub, Keycloak, etc.), y después de la autenticación, se establece una sesión en Redis. Tus usuarios pueden acceder con sus cuentas de Google o GitHub sin que tú tengas que gestionar contraseñas.

Plugin de rate limiting avanzado

El middleware RateLimit de serie es funcional, pero hay plugins como traefik-rate-limit que ofrecen más flexibilidad. Por ejemplo, rate limiting por ruta, por cabecera, o por método HTTP.

experimental:
  plugins:
    advanced-ratelimit:
      moduleName: github.com/dcmcand/traefik-rate-limit
      version: v1.0.0

http:
  middlewares:
    rate-limit-api:
      plugin:
        advanced-ratelimit:
          rules:
            - path: "/api/login"
              method: "POST"
              average: 5
              burst: 10
              period: "1m"
            - path: "/api/*"
              method: "GET"
              average: 100
              burst: 200
              period: "1m"

Con esto puedes tener límites diferentes para cada endpoint de tu API. El login permite 5 peticiones por minuto, mientras que las consultas GET permiten 100.

Configuración avanzada de plugins

Una vez que tienes claros los conceptos básicos, hay técnicas más avanzadas que te van a venir bien cuando tu infraestructura crezca.

Encadenamiento de plugins y middlewares

Los plugins son middlewares, así que puedes combinarlos con los middlewares nativos en el mismo router. El orden en que los pongas importa, y mucho.

http:
  routers:
    mi-app:
      rule: Host(`app.dominio.com`)
      middlewares:
        - geoblock-europa@file
        - crowdsec-bouncer@file
        - ratelimit-basico@file
        - security-headers@file
      service: mi-app-service

En este ejemplo, la petición pasa por cuatro filtros antes de llegar al servicio:

1. Geobloqueo: filtra por país de origen.
2. CrowdSec: bloquea IPs maliciosas conocidas.
3. RateLimit: evita abusos de peticiones.
4. Security Headers: añade cabeceras de seguridad a la respuesta.

Si pones el geobloqueo después de CrowdSec, estarías haciendo la comprobación de geolocalización incluso para IPs que luego va a bloquear CrowdSec. Es un desperdicio de recursos. Pon primero los filtros más baratos y luego los más caros.

Uso de variables de entorno en la configuración de plugins

En la configuración estática no puedes usar variables de entorno directamente para los parámetros de los plugins. Pero sí puedes usar el plugin envsubst o configurar un proceso que genere el archivo dinámico a partir de plantillas.

Una forma práctica es tener un script que genere el YAML,

#!/bin/bash
cat > /etc/traefik/dynamic/plugins.yml <<EOF
http:
  middlewares:
    crowdsec-bouncer:
      plugin:
        crowdsec:
          crowdsecLapiUrl: "${CROWDSEC_URL:-http://crowdsec:8080}"
          crowdsecLapiKey: "${CROWDSEC_API_KEY}"
          crowdsecMode: "live"
EOF

Esto te permite mantener las claves de API fuera del repositorio y pasarlas como variables de entorno al contenedor de Traefik.

Plugins condicionales con reglas de router

No tienes por qué aplicar el mismo plugin a todas las rutas. Puedes combinar reglas de router para aplicar plugins solo cuando se cumplan ciertas condiciones.

http:
  routers:
    api-publica:
      rule: "Host(`api.dominio.com`) && PathPrefix(`/public`)"
      middlewares:
        - rate-limit-publico@file
      service: api-service

    api-privada:
      rule: "Host(`api.dominio.com`) && PathPrefix(`/private`)"
      middlewares:
        - geoblock-espana@file
        - auth-oidc@file
        - rate-limit-privado@file
      service: api-service

De esta forma, la parte pública de tu API está abierta al mundo con solo rate limiting, mientras que la parte privada requiere geobloqueo y autenticación.

Probar plugins localmente

Antes de desplegar un plugin en producción, te recomiendo que lo pruebes en local. Puedes levantar Traefik en tu máquina con Docker Compose y hacer peticiones de prueba con curl.

# Prueba básica de geobloqueo
curl -H "Host: app.dominio.com" http://localhost

# Simular una IP de otro país
curl -H "Host: app.dominio.com" -H "X-Forwarded-For: 1.1.1.1" http://localhost

Si el plugin devuelve un 403, sabes que está funcionando. Si devuelve un 200, revisa la configuración.

Troubleshooting de plugins

Los plugins son potentes, pero cuando fallan, el diagnóstico puede ser complicado. Te dejo una guía de los problemas más comunes y cómo resolverlos.

Plugin no se descarga

Si Traefik no arranca porque no encuentra el plugin, el primer sitio donde mirar son los logs,

docker logs traefik | grep -i plugin

O si usas Traefik directamente,

journalctl -u traefik | grep -i plugin

Los errores más comunes son,

• Módulo incorrecto: el moduleName no existe o está mal escrito. Comprueba que la ruta de GitHub es exacta.
• Versión incorrecta: la etiqueta v0.3.0 no existe en el repositorio. Ve a GitHub y mira las releases disponibles.
• Sin conexión a internet: Traefik necesita descargar el plugin al arrancar. Si estás en un entorno aislado, tendrás que precargar los plugins.
• Plugin no compatible: algunos plugins son para v2 y no funcionan en v3. Revisa la documentación.

Error de WASM

Al ser plugins compilados a WebAssembly, puedes encontrarte con errores de compilación o de ejecución en el sandbox,

level=error msg="plugin: failed to compile wasm module: ...

Esto suele pasar cuando,

• La versión de Go con la que se compiló el plugin no es compatible con tu versión de Traefik.
• El plugin tiene dependencias que no se resuelven correctamente.
• El plugin usa características de Go que no están soportadas en WASM.

En estos casos, prueba con una versión anterior del plugin o busca si hay una versión específica para tu versión de Traefik.

La API de geolocalización falla

Si usas el plugin de geobloqueo y de repente deja de funcionar, lo más probable es que la API de geolocalización haya alcanzado su límite. Las APIs gratuitas tienen rate limiting.

Para diagnosticarlo,

# Comprueba si la API responde
curl -s https://api.geo.ipify.org
# Si no responde, cambia a otra API o aumenta el cacheSize

Soluciones,

• Aumenta cacheSize para reducir las llamadas a la API.
• Cambia a otra API gratuita como ip-api.com.
• Monta tu propia instancia de GeoIP con MaxMind.

El plugin no bloquea como esperas

Si configuras un plugin de geobloqueo y ves que llegan peticiones de países que deberías estar bloqueando, revisa estos puntos,

• allowLocal: si está a true, las IPs de la red local (192.168.x.x, 10.x.x.x, etc.) pasan sin geolocalización. Si tu servidor está detrás de un proxy inverso o balanceador, la IP que ve Traefik puede ser local.
• forceMatch: si está a false, las IPs que no se pueden geolocalizar pasan. Pónlo a true si quieres ser restrictivo.
• Caché obsoleta: si cambias la configuración, la caché puede seguir devolviendo resultados antiguos. Reinicia Traefik o espera a que expire el cacheTimeout.
• IP incorrecta: si tienes Traefik detrás de Cloudflare o similar, asegúrate de que está viendo la IP real del cliente. Puede que necesites el plugin real-ip antes del geobloqueo.

Para depurar, puedes activar el log de depuración de Traefik,

log:
  level: DEBUG

Esto te mostrará información detallada de cada plugin. Úsalo con cuidado en producción porque genera mucho volumen de logs.

Conflicto entre plugins

Algunos plugins pueden interferir entre sí. Por ejemplo, un plugin que modifica cabeceras puede romper la autenticación de otro plugin. O un plugin que transforma el cuerpo puede impedir que el compresor de contenido funcione correctamente.

Regla general: los plugins que modifican cabeceras deben ir al principio de la cadena, los que transforman el cuerpo al final, y los de seguridad en medio. Pero esta regla no es universal. Cada combinación es un mundo, así que prueba siempre en un entorno de staging antes de desplegar.

El plugin funciona pero ralentiza el servicio

Los plugins en WASM tienen un overhead, pero normalmente es mínimo. Si notas lentitud,

• Comprueba que el plugin no está haciendo llamadas a APIs externas en cada petición (geobloqueo, por ejemplo). Aumenta la caché.
• Revisa si hay plugins que procesan el cuerpo de la respuesta (transform-body). Si puedes evitarlos, mejor.
• Mide el tiempo que tarda cada middleware con las métricas de Traefik,

curl -s http://localhost:8080/api/http/middlewares | jq '.'

Si un middleware en concreto añade más de 100ms, investiga por qué.

Versiones incompatibles

No todos los plugins funcionan con todas las versiones de Traefik. Cuando actualices Traefik, es posible que algún plugin deje de funcionar. Por eso te recomiendo que,

1. Especifiques siempre la versión del plugin. No dejes que use la última disponible.
2. Antes de actualizar Traefik, consulta la compatibilidad del plugin en su repositorio de GitHub.
3. Mantén un entorno de pruebas donde puedas verificar que todo sigue funcionando después de la actualización.

Buenas prácticas

1. Revisa los plugins que instalas. Son código que se ejecuta en tu proxy inverso, dentro de un sandbox WASM, pero sigue siendo código de terceros. Usa solo plugins de fuentes fiables y revisa el repositorio antes de instalarlos.
2. Especifica la versión del plugin. No dejes que Traefik use la última siempre, porque una actualización podría cambiar el comportamiento o romper algo. Fija una versión y actualízala cuando toque, de forma controlada.
3. Declara los plugins en el File provider, no en las labels de Docker. Es más limpio, más fácil de mantener, y puedes usar un solo archivo para todos los plugins. Las labels son prácticas para cosas sencillas, pero para plugins con configuraciones largas, el File provider es muy superior.
4. No abuses de los plugins. Cada plugin añade complejidad, consume recursos, y es un punto potencial de fallo. Usa solo los que realmente necesites. Si puedes hacer algo con un middleware nativo, hazlo con el middleware nativo.
5. Comprueba los logs si un plugin no funciona:

docker logs traefik | grep -i plugin

6. Prueba en staging primero. Los plugins se ejecutan en el flujo de peticiones de tu proxy. Un plugin mal configurado puede tirar todo el servicio. Siempre prueba antes en un entorno de staging.
7. Monitoriza el rendimiento. Después de añadir un plugin, monitoriza la latencia de tus rutas para detectar degradaciones. Las métricas de Traefik son tu mejor aliado aquí.
8. Mantén los plugins actualizados. Los plugins reciben parches de seguridad y mejoras de rendimiento. Revisa periódicamente si hay nuevas versiones de los plugins que usas.
9. Documenta qué plugins usas y por qué. Cuando vuelvas a mirar la configuración dentro de seis meses, agradecerás tener una nota que explique por qué usas ese plugin y qué hace exactamente.
10. No mezcles plugins de autenticación. Si usas OIDC, no añadas BasicAuth encima a menos que sea necesario. Los plugins de autenticación pueden interferir entre sí y dejar a tus usuarios sin acceso.

Conclusión

Los plugins son una forma potente de extender Traefik más allá de los middlewares de serie. Con el catálogo de plugins disponible, puedes añadir geobloqueo, integración con CrowdSec, fail2ban, Coraza WAF, autenticación OIDC, transformaciones de cuerpo, CORS avanzado, y mucho más.

La clave está en usarlos con cabeza. No instales plugins sin necesidad, especifica siempre las versiones, y prueba antes en staging. Si sigues estas pautas, los plugins serán una herramienta fantástica en tu cinturón de utilidades de Traefik.

En el próximo capítulo veremos TCP y UDP, para enrutar servicios que no usan HTTP, como bases de datos, servidores de juego o de voz. Ahí también se pueden usar plugins, pero con algunas limitaciones que veremos entonces.

Dale caña al catálogo de plugins, experimenta, y sobre todo, asegúrate de que cada plugin que añades tiene una razón de ser. Tu proxy inverso te lo agradecerá.

Más información

• Traefik Documentation — Plugins / Extend Traefik — Documentación oficial sobre sistemas de plugins (Yaegi y WASM)
• Traefik Documentation — Experimental / Plugins (reference) — Configuración de referencia para declarar plugins en la configuración estática
• Plugin Catalog — plugins.traefik.io — Catálogo oficial de plugins para Traefik
• Blog atareao.es — Traefik: Plugins — Fuente original de este capítulo