magnus919_agent-skills/traefik/references/plugins-extend.md

Plugins & Extending Traefik

Traefik supports two plugin systems for extending its capabilities with custom middlewares and providers.

Plugin Systems Comparison

Feature	Yaegi	WebAssembly (WASM)
Language	Go	Any language compiling to WASM (Go, Rust, C++, TinyGo)
Compilation	Not required (interpreted)	Required (compiled to .wasm binary)
Performance	Interpreted	Near-native
Hot-reload	Yes	No (binary change requires reload)
Safety	Go sandbox	WASM sandbox
Extensibility	Middleware + Provider	Middleware only
Use case	Rapid development, prototyping	Production-grade, performance-critical
Plugin Catalog	Available	Available

Plugin Catalog

Browse available plugins: https://plugins.traefik.io/

The Plugin Catalog is accessible from the Traefik Dashboard under the Plugins menu entry. Each plugin provides:

• Installation instructions (static config snippet)
• Dynamic configuration syntax
• Usage examples

Configuring Plugins (Static Config)

Remote Plugins (from catalog)

# Static config
experimental:
  plugins:
    plugin-name:
      moduleName: "github.com/org/plugin"
      version: "v0.1.0"
      # Optional settings (WASM only):
      settings:
        envs:
          - "CACHE_TTL=300"
        mounts:
          - "/data/cache:/cache"

Local Plugins (development)

experimental:
  localPlugins:
    plugin-name:
      moduleName: "github.com/org/plugin"
      settings:
        envs:
          - "DEBUG=true"

Using Plugins in Dynamic Config

Plugins are referenced as middlewares with the @plugin provider namespace:

# Dynamic config (File provider)
http:
  middlewares:
    my-auth:
      plugin:
        auth-plugin-name:
          headerName: "X-API-Key"
          secret: "my-secret"

http:
  routers:
    app:
      rule: "Host(`app.example.com`)"
      middlewares:
        - "my-auth@file"          # File-based middleware
        - "plugin-name@plugin"    # Plugin middleware

  services:
    app:
      loadBalancer:
        servers:
          - url: "http://backend:80"

With Docker labels:

labels:
  - "traefik.http.middlewares.my-plugin.plugin.plugin-name.key=value"
  - "traefik.http.routers.app.middlewares=my-plugin@plugin"

Plugin Development

Yaegi Plugin (Go, no compilation)

Create a Go package with a module path and implement the middleware/provider interface. Import pattern:

package myplugin

import (
    "context"
    "net/http"
)

func New(ctx context.Context, conf map[string]interface{}) (func(next http.Handler) http.Handler, error) {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(rw http.ResponseWriter, req *http.Request) {
            // Custom logic
            next.ServeHTTP(rw, req)
        })
    }, nil
}

WASM Plugin (any language)

Compile to a .wasm binary following the http-wasm specification (https://http-wasm.io/). HTTP middleware handler with request/response manipulation capability.

Development Resources

• Developer docs: https://plugins.traefik.io/install
• Plugin creation guide: https://plugins.traefik.io/create
• Plugin catalog submission: Publish to https://plugins.traefik.io/ for community use

Provider Plugins

Yaegi plugins can extend Traefik with custom providers, enabling dynamic configuration from any source:

experimental:
  plugins:
    my-provider-plugin:
      moduleName: "github.com/org/provider-plugin"
      version: "v0.1.0"

providers:
  plugin:
    my-provider-plugin:
      endpoint: "http://custom-source:8080"
      pollInterval: "30s"

Security Considerations

• Plugins run with the same privileges as Traefik itself
• WASM provides stronger isolation (sandboxed by design)
• Only install plugins from trusted sources (verified hashes)
• Test plugins in staging before production deployment
• Plugin hash verification is optional but recommended for remote plugins:

experimental:
  plugins:
    plugin-name:
      moduleName: "github.com/org/plugin"
      version: "v0.1.0"
      hash: "sha256:abc123..."

FastProxy (Experimental)

FastProxy is an experimental HTTP/2 multiplexing optimization that reduces connection overhead to backends:

# Static config
experimental:
  fastProxy: true

FastProxy connects to backend servers using a shared HTTP/2 connection pool, reducing connection churn for services with many concurrent requests. Available in Traefik v3.x experimental channel.