Traefik Plugins erstellen: Eigene Middleware entwickeln

Traefik Plugins erstellen lohnt sich, wenn die vorhandenen Middlewares eine Anforderung nicht abdecken. Du entwickelst dafür ein kleines Go-Paket oder ein WASM-Modul, aktivierst es statisch und verwendest es anschließend wie jede andere Middleware. Für den Einstieg ist ein Yaegi-Plugin mit klarer Konfiguration der einfachste Weg.

Dieser Leitfaden zeigt den aktuellen Aufbau, eine funktionierende Header-Middleware und die Trennung von statischer Installation und dynamischer Nutzung. So vermeidest du typische Fehler bei Versionen, Konfiguration und dem Einsatz in Produktion.

Stand: 05.10.2026

Auf einen Blick

• Traefik unterstützt Go-basierte Yaegi-Plugins und WebAssembly-Plugins.
• Die Installation eines Plugins gehört in die statische Konfiguration.
• Die Middleware-Instanz wird getrennt davon dynamisch konfiguriert und am Router referenziert.
• Nutze für Standardaufgaben zuerst die eingebauten Middlewares; ein Plugin erhöht Wartungs- und Sicherheitsaufwand.

Wann solltest du Traefik Plugins erstellen?

Ein Plugin ist sinnvoll, wenn du HTTP-Anfragen mit eigener Logik verändern oder prüfen musst und Traefik dafür keine eingebaute Middleware bietet. Denkbar sind eine organisationsspezifische Header-Prüfung, eine Anbindung an einen internen Dienst oder eine kontrollierte Umleitung.

Für Basic Auth, Rate Limiting, Header-Manipulation oder Redirects brauchst du meist kein eigenes Plugin. Traefik bringt dafür Middlewares mit. Das ist einfacher zu testen und reduziert den Code, den du pflegen musst. Einen Überblick zur sicheren Proxy-Konfiguration findest du auch im Beitrag Traefik und Ingress-Sicherheit.

Welche Voraussetzungen gelten für ein Yaegi-Plugin?

Du brauchst eine aktuelle Go-Entwicklungsumgebung, Git und eine Traefik-Instanz zum Testen. Das Plugin ist ein Go-Modul. Für den Plugin Catalog muss der Quellcode öffentlich erreichbar und versioniert sein. Verwende deshalb einen unveränderlichen Git-Tag statt eines Branch-Namens.

Plane außerdem ein Staging-System ein. Plugins können den Datenfluss von Traefik verändern. Prüfe daher Fehlerpfade, Timeouts und das Verhalten bei ungültiger Konfiguration, bevor du sie an produktive Router hängst. Für Container-Setups helfen die Grundlagen aus Docker Compose Grundlagen.

Traefik Plugins erstellen: So legst du das Projekt an

1. Lege ein neues Repository und ein Go-Modul an.
2. Definiere eine Config sowie CreateConfig für sichere Standardwerte.
3. Implementiere New und einen Handler mit ServeHTTP.
4. Teste die Middleware mit httptest, tagge eine Version und hinterlege die Metadaten für den Catalog.

mkdir request-header-plugin
cd request-header-plugin
go mod init github.com/deinname/request-header-plugin
git init

Die Moduladresse muss später exakt zu moduleName passen. Wähle deshalb vor dem ersten Release die endgültige Repository-Adresse. Das Paket benötigt keine Traefik-Interna; es arbeitet mit den Standardtypen aus net/http.

Wie sieht eine kleine Middleware aus?

Das folgende Beispiel setzt einen konfigurierbaren Request-Header. Es validiert die Konfiguration beim Start, statt erst während einer Anfrage mit einem unklaren Fehler zu scheitern.

package requestheader

import (
  "context"
  "fmt"
  "net/http"
)

type Config struct {
  Header string `json:"header"`
  Value  string `json:"value"`
}

func CreateConfig() *Config {
  return &Config{Header: "X-Managed-By", Value: "traefik"}
}

type middleware struct {
  next http.Handler
  header string
  value string
}

func New(_ context.Context, next http.Handler, cfg *Config, _ string) (http.Handler, error) {
  if cfg.Header == "" {
    return nil, fmt.Errorf("header must not be empty")
  }
  return &middleware{next: next, header: cfg.Header, value: cfg.Value}, nil
}

func (m *middleware) ServeHTTP(rw http.ResponseWriter, req *http.Request) {
  req.Header.Set(m.header, m.value)
  m.next.ServeHTTP(rw, req)
}

Gib keine Tokens, Passwörter oder personenbezogenen Daten in Logs aus. Wenn dein Plugin externe Dienste aufruft, setze feste Timeouts und behandle Ausfälle bewusst. Ein Proxy darf bei einem Nebenaufruf nicht unkontrolliert alle Anfragen blockieren.

Wie veröffentlichst du die Plugin-Metadaten?

Lege im Repository eine Datei .traefik.yml an. Sie beschreibt das Plugin für den Catalog. Der Typ middleware passt zum Beispiel oben. Die Angaben müssen zum Repository und Paket passen.

displayName: Request Header
type: middleware
import: github.com/deinname/request-header-plugin
summary: Setzt einen konfigurierbaren Request-Header
testData:
  header: X-Managed-By
  value: traefik

Führe vor dem Release Unit-Tests aus und erstelle dann einen annotierten oder normalen Versions-Tag. Erst mit einer festen Version kann Traefik die gewünschte Revision reproduzierbar laden.

go test ./...
git add .
git commit -m "Erstes Plugin-Release"
git tag v0.1.0
git push origin main --tags

Wie installierst und verwendest du das Plugin?

Die Plugin-Installation ist Teil der statischen Traefik-Konfiguration. Nach einer Änderung startet Traefik das Plugin beim nächsten Neustart der Instanz. Lege die Middleware-Instanz anschließend in einer dynamischen Datei an, die dein File Provider einliest. Diese Trennung ist wichtig: Router und Middlewares sind dynamische Konfiguration.

# traefik.yml – statische Konfiguration
experimental:
  plugins:
    request-header:
      moduleName: github.com/deinname/request-header-plugin
      version: v0.1.0

providers:
  file:
    filename: /etc/traefik/dynamic.yml

# dynamic.yml – dynamische Konfiguration
http:
  middlewares:
    add-managed-header:
      plugin:
        request-header:
          header: X-Managed-By
          value: traefik
  routers:
    app:
      rule: Host(`app.example.com`)
      service: app
      middlewares:
        - add-managed-header

Der Name unter experimental.plugins ist der Plugin-Bezeichner. Unter http.middlewares legst du eine konkrete Instanz mit eigenen Werten an. Mehrere Router können dieselbe Instanz verwenden. Bei Docker oder Kubernetes bleiben die Konzepte gleich; nur der Ort der dynamischen Konfiguration ändert sich. Für Kubernetes-Konfigurationen ist Helm Charts erklärt eine passende Ergänzung.

Wie testest du sicher vor dem Produktiveinsatz?

1. Starte eine isolierte Traefik-Instanz mit der statischen und dynamischen Testkonfiguration.
2. Prüfe eine erfolgreiche Anfrage sowie eine Anfrage mit ungültigen Plugin-Werten.
3. Kontrolliere im Upstream, ob der erwartete Header ankommt.
4. Aktiviere das Plugin erst danach an einem begrenzten produktiven Router und beobachte Fehlerquote sowie Latenz.

Halte die Plugin-Version im Deployment fest. Aktualisiere sie nicht ungetestet, auch wenn eine neue Version im Repository verfügbar ist. Das erleichtert einen Rollback: Du setzt die vorherige, bekannte Versionsnummer und startest Traefik kontrolliert neu.

Fazit

Traefik Plugins erstellen ist keine Abkürzung für jede Routing-Aufgabe, aber eine saubere Erweiterungsmöglichkeit für echte Lücken. Beginne mit einer kleinen, getesteten Yaegi-Middleware, installiere sie statisch und konfiguriere ihre Nutzung dynamisch. Feste Versionen, Staging und zurückhaltende Berechtigungen machen den Einsatz beherrschbar.

Quellen

• Traefik Docs: Extend Traefik
• Traefik Plugin Catalog: Developing Plugins
• Traefik: plugindemo auf GitHub

Häufige Fragen