Traefik v3 Migration: Sicher von v2 umsteigen

Eine Traefik v3 Migration gelingt am sichersten in drei Phasen: Konfiguration vorbereiten, v3 parallel testen und Routing schrittweise umstellen. Traefik v3 akzeptiert viele v2-Routing-Konfigurationen zunächst weiter. Dennoch musst du die Installationskonfiguration prüfen, Logs beobachten und einen getesteten Rollback bereithalten.

Stand: 04.10.2026

Auf einen Blick

• Traefik v3 bietet für Routing-Konfigurationen einen Kompatibilitätspfad für v2-Syntax.
• Prüfe zuerst die Installationskonfiguration: EntryPoints, Provider, API, Logging und Zertifikate.
• Stelle Regeln einzeln auf die v3-Syntax um, statt alles in einem Release zu ändern.
• Nutze Staging, Monitoring und einen eingeübten Rollback vor dem Produktivwechsel.

Was ändert sich bei der Traefik v3 Migration wirklich?

Die frühere Darstellung eines vollständigen Konfigurationsumbruchs wäre irreführend. Laut Traefik sind die Breaking Changes beim Wechsel von v2 auf v3 bewusst begrenzt. Besonders wichtig: Für Routing-Konfigurationen gibt es Abwärtskompatibilität mit der v2-Syntax. Das betrifft etwa Docker-Labels, Kubernetes-Ressourcen und Dateikonfigurationen.

Die Installationskonfiguration, früher oft als statische Konfiguration bezeichnet, verdient dennoch besondere Aufmerksamkeit. Sie wird beim Start geladen und umfasst unter anderem EntryPoints sowie Provider. Routing-Konfigurationen kommen dagegen über Provider und können ohne Neustart neu geladen werden. TLS-Zertifikate gehören ebenfalls zur Routing-Konfiguration.

Traefik v3 Migration vorbereiten

Beginne nicht mit dem Container-Tag. Sichere zuerst die aktuelle Konfiguration, die Deployment-Dateien und die verwendeten Images. Dokumentiere außerdem alle EntryPoints, Domains, Zertifikatsresolver, Middlewares und kritischen Routen. Dadurch erkennst du nach dem Test schnell, was fehlt.

1. Exportiere oder versioniere traefik.yml, dynamische Dateien, Docker-Compose-Dateien und Kubernetes-Manifeste.
2. Erstelle eine Liste kritischer URLs, Redirects, WebSockets und TLS-Endpunkte.
3. Prüfe die offiziellen Details zu Änderungen der Installations- und Routing-Konfiguration.
4. Lege ein v2-Image oder das vorherige Deployment als Rollback fest.

Vermeide dabei gemischte Quellen für dieselbe Einstellung. Die Installationskonfiguration darf laut Dokumentation entweder aus einer Datei, CLI-Argumenten oder Umgebungsvariablen stammen; diese Methoden sind gegenseitig ausschließend. Wähle deshalb für den Test denselben Konfigurationsweg wie in Produktion.

# Verfügbare Optionen des konkret eingesetzten v3-Images ansehen
docker run --rm traefik:v3.7 --help

# Testinstanz mit einer expliziten Installationskonfiguration starten
docker run --rm \
  -p 8080:80 \
  -v "$PWD/traefik-v3.yml:/etc/traefik/traefik.yml:ro" \
  traefik:v3.7

Die Versionsangabe im Beispiel ist kein Ersatz für dein Release-Management. Pinne im Deployment ein geprüftes Image-Tag und aktualisiere es nach deinem eigenen Testzyklus. Lies vor jedem Minor-Upgrade zusätzlich die Hinweise zur jeweiligen v3-Minor-Migration.

Wie hilft der Kompatibilitätsmodus bei der Traefik v3 Migration?

Traefik v3 verwendet für Regeln standardmäßig die v3-Syntax. Wenn du bestehende v2-Routen zunächst unverändert betreiben willst, setzt du in der Installationskonfiguration den Standard gezielt auf v2. Das verschafft Zeit, ersetzt aber keine Bereinigung.

# traefik.yml – nur als temporärer Übergang
core:
  defaultRuleSyntax: v2

Damit bleiben v2-Regeln der Standard. Migriere anschließend einen nicht kritischen Router, teste ihn und fahre fort. Sobald alle Router die v3-Syntax verwenden und keine Deprecation-Warnungen mehr erscheinen, entfernst du diesen Abschnitt wieder. Für komplexe eigene Erweiterungen solltest du auch dein Traefik-Plug-in gegen die Zielversion testen.

Welche Regeln musst du konkret prüfen?

Konzentriere dich auf Regeln mit regulären Ausdrücken. Die v2-Syntax erlaubte bei HostRegexp und PathRegexp häufig benannte Platzhalter in geschweiften Klammern. Die v3-Regelsyntax orientiert sich an Go-Regulärausdrücken und verwendet diese Schreibweise nicht. Ein Beispiel macht den Unterschied sichtbar:

# v2-Regelsyntax
HostRegexp(`{subdomain:[a-z]+}.example.com`)

# v3-Regelsyntax
HostRegexp(`[a-z]+\\.example\\.com`)

Übernimm die v3-Variante nicht blind: Sie beschreibt hier bewusst nur die gewünschte Host-Struktur. Prüfe bei jeder Regel, ob Capture-Gruppen, Prioritäten oder weitere Matcher benötigt werden. Auch Docker-Labels und Kubernetes-Objekte gehören in diesen Test. Wenn du Traefik mit DNS-Automatisierung verbindest, kontrolliere anschließend die ExternalDNS- und IngressRoute-Konfiguration.

So testest du den Wechsel ohne Risiko

Ein sauberer Start ohne Fehlermeldung ist die erste Prüfung, nicht die letzte. Aktiviere in der isolierten Umgebung aussagekräftige Logs und teste die zuvor dokumentierten Endpunkte. Prüfe außerdem Zertifikate, Weiterleitungen, Authentifizierung und die Erreichbarkeit der Backends.

1. Starte Traefik v3 in einer Staging-Umgebung mit der angepassten Installationskonfiguration.
2. Suche im Startlog nach unbekannten Optionen, Deprecation-Hinweisen und Provider-Fehlern.
3. Rufe kritische Pfade mit HTTP und HTTPS ab und kontrolliere Statuscode sowie Weiterleitungen.
4. Teste Middlewares wie Authentifizierung, Rate Limiting und Header separat.
5. Vergleiche Fehlerquote und Antwortzeiten mit der v2-Instanz.

log:
  level: DEBUG

accessLog: {}

Nutze DEBUG nur während der Fehlersuche, denn die Ausgabe ist umfangreich. Für den Regelbetrieb sind strukturierte Access Logs und Metriken hilfreicher. Eine Einführung in passende Kennzahlen findest du im Artikel zu Kubernetes-Monitoring mit Grafana und Prometheus.

Dashboard und API korrekt absichern

Das Dashboard ist kein eigenständiger, automatisch sicherer Verwaltungsbereich. Aktiviere es nur bei Bedarf und route den internen Service api@internal über einen bewusst definierten Router. Schütze diesen Router mindestens per Authentifizierung und schränke den Zugriff zusätzlich per Netzwerk oder IP-Allowlist ein.

# Installationskonfiguration
api:
  dashboard: true

# Dynamische Dateikonfiguration
http:
  routers:
    traefik-dashboard:
      rule: Host(`traefik.example.com`)
      service: api@internal
      middlewares:
        - admin-auth

Lege Zugangsdaten nicht unverschlüsselt in ein Repository. Nutze je nach Plattform Secrets. Das gilt ebenso für DNS-Provider-Tokens und Zertifikatszugänge. Weitere Grundlagen für sichere Container-Umgebungen bündelt unser Beitrag zu Docker-Security.

Produktiv umstellen und zurückrollen

Plane die Umstellung als kontrolliertes Deployment. Starte mit wenig kritischem Traffic oder einer einzelnen Instanz, sofern deine Architektur das zulässt. Beobachte dabei kontinuierlich Ingress-Traffic, Fehlerquote und TLS-Handshakes. Halte das getestete v2-Deployment bereit, damit du bei Auffälligkeiten unmittelbar zurückwechseln kannst.

Nach dem Upgrade migrierst du die Routing-Konfiguration weiter. Entferne erst zum Schluss den Kompatibilitätsmodus. Damit bleibt die Traefik v3 Migration nachvollziehbar, und jede Änderung ist einem Test zugeordnet.

Fazit

Die Traefik v3 Migration ist kein Anlass für einen kompletten Neuaufbau. Prüfe die Installationskonfiguration sorgfältig, nutze den v2-Kompatibilitätspfad für Routing und stelle Regeln schrittweise um. Mit Staging, Logs, Metriken und einem getesteten Rollback reduzierst du das Risiko deutlich.

Quellen

• Traefik: Migration Guide v2 zu v3
• Traefik: Konfigurationsänderungen für v3
• Traefik: Konfigurationsüberblick

Häufige Fragen