Traefik v2 zu v3 Migration: Was ändert sich?

Unterschiede zwischen Traefik v2 und v3

Eine Migration von Traefik v2 zu v3 besteht hauptsächlich aus Umbenennungen. Die bekannteste Änderung ist das Middleware-Element ipWhiteList, das nun ipAllowList heißt. Darüber hinaus verschärft v3 die Syntax der Router-Regeln (PathPrefix verliert seine Regex-Funktionen, mehrere Matcher wurden umbenannt oder entfernt). Einige Provider und Optionen wurden vollständig entfernt. Alle anderen Funktionen bleiben erhalten: Entrypoints, das ACME-Zertifikats-Setup, der Docker-Label-Workflow und Ihr acme.json werden übernommen. v3 enthält zudem einen Kompatibilitätsmodus, der die v2-Regelsyntax beibehält. So können Sie zuerst das Binary aktualisieren und die Regeln nacheinander pro Service umschreiben, anstatt alles in einer riskanten Nacht zu ändern.

Dieser Leitfaden setzt das Label-basierte Docker Compose Setup aus dem Traefik Reverse Proxy Guide voraus. Diese Seite ist v3-nativ; diese Seite ist für Systeme gedacht, die noch ein traefik:v2 Tag verwenden.

Umbenennungen und Entfernungen

• ipWhiteList heißt nun ipAllowList, sowohl für die HTTP- als auch für die TCP-Middleware. Die Optionen darin sind unverändert, daher behält sourcerange exakt die gleiche Bedeutung. Aktuelle v3-Releases, einschließlich v3.5, akzeptieren den alten Namen noch als veralteten Alias (deprecated alias) und führen die Liste weiterhin auf. Diese Umbenennung führt also nicht zu Ausfällen. Führen Sie die Umbenennung dennoch durch: Der Alias ist für die Entfernung geplant und verschwindet ohne Fehlermeldung aus der Deprecation-Liste.
• providers.docker.swarmMode=true wurde entfernt. Swarm erhält einen eigenen Provider, konfiguriert als providers.swarm.endpoint.
• Der Abschnitt pilot wurde vollständig entfernt.
• experimental.http3 wurde entfernt. HTTP/3 wird direkt am Entrypoint aktiviert.
• tls.caOptional wurde aus den Providern und aus der forwardAuth-Middleware entfernt.
• Der InfluxDB v1 Metrics-Provider, der Rancher-Provider und der Marathon-Provider wurden entfernt.
• Tracing wurde zu OpenTelemetry verschoben. Die dedizierten Tracing-Backends, einschließlich der Jaeger- und Zipkin-Integrationen, wurden entfernt; v3 exportiert stattdessen OTLP (das OpenTelemetry-Protokoll).
• Die veralteten ssl*-Optionen innerhalb der Headers-Middleware (sslRedirect, sslHost und weitere) wurden entfernt. Entrypoint-Redirections und die redirectScheme-Middleware haben diese ersetzt.

Diese Entfernungen sind bedeutsamer, als sie erscheinen, da Traefik den Start verweigert, wenn die statische Konfiguration eine unbekannte Option enthält. Eine verbleibende pilot- oder swarmMode-Zeile stoppt den Container beim Booten mit einer incompatible deprecated static option found-Meldung, die die verbleibende Option benennt; eine Option, die Traefik noch nie gesehen hat (ein Tippfehler oder tls.caOptional), stoppt den Prozess stattdessen mit field not found. Bereinigen Sie die statische Konfiguration, bevor Sie das Image-Tag ändern.

Ein Middleware-Name, den Traefik tatsächlich nicht kennt (ein Tippfehler oder ein Name, der entfernt statt als Alias beibehalten wurde), führt zu einem anderen Fehler: Der Router, der darauf verweist, lädt mit einem Fehler statt einer Route, das Dashboard markiert ihn und die API meldet middleware "offce@docker" does not exist. Anfragen an diesen Hostnamen erhalten einen 404-Fehler, da der Router nicht gestartet ist. Beachten Sie, dass ipwhitelist in der aktuellen v3 NICHT in diese Kategorie fällt: Es bleibt als veralteter Alias erhalten, sodass ein nicht umbenanntes Label weiterhin lautlos funktioniert.

Die Syntax der Regeln ändert sich

Regeln ermöglichen das eigentliche Rewriting. Die Änderungen in v3:

• Werte innerhalb von Matchern müssen in Backticks gesetzt werden. v2 akzeptierte auch doppelte Anführungszeichen; v3 tut dies nicht. Daher muss Host("app.example.com") zu Host(app.example.com) geändert werden.
• PathPrefix unterstützt keine regulären Ausdrücke oder Platzhalter im {id}-Stil mehr. Eine v2-Regel wie PathPrefix(/api/{version:v[0-9]+}) muss in einen PathRegexp-Matcher in Go-Regulärer-Ausdruck-Syntax umgewandelt werden.
• Matcher akzeptieren jetzt nur noch einen einzelnen Wert. v2 erlaubte Host(app.example.com,www.example.com); v3 erfordert Host(app.example.com) || Host(www.example.com). Die Ausnahmen sind Header, HeaderRegexp, Query und QueryRegexp, die weiterhin einen Namen plus einen Wert akzeptieren.
• Headers und HeadersRegexp wurden in Header und HeaderRegexp umbenannt.
• HostHeader wurde entfernt. Verwenden Sie Host, was in v3 dasselbe matcht.
• Zwei Matcher sind neu: QueryRegexp und ClientIP zum Matchen der Client-Adresse innerhalb einer Regel.

Die gute Nachricht: Eine einfache Host(app.example.com)-Regel mit Backticks entspricht bereits der gültigen v3-Syntax. Die meisten kleinen Compose-Setups verwenden genau diese Schreibweise. Das bedeutet, dass die meisten Labels ohne Änderungen an den Regeln migriert werden können.

Überprüfen Sie Ihre Labels vor dem Start

Sie können den Umfang Ihrer Migration mit einem einzigen Suchvorgang ermitteln. Jede kritische Label-Änderung hinterlässt ein Muster, das mit grep gefunden werden kann:

grep -rnE 'ipwhitelist|HostHeader|Headers\(|PathPrefix\(`[^`]*\{|Host\(`[^`]*`,' docker-compose*.yml

Jeder Treffer entspricht einer zu bearbeitenden Zeile. ipwhitelist wird zu ipallowlist. HostHeader wird zu Host. Headers wird zu Header. Ein {...}-Platzhalter innerhalb von PathPrefix wird zu einem PathRegexp-Matcher. Ein Komma innerhalb von Host() wird zu zwei durch || verbundenen Host()-Matchern. Null Treffer bedeutet, dass Ihre Labels bereits der gültigen v3-Syntax entsprechen. In diesem Fall reduziert sich die Migration auf die statische Konfiguration plus das Image-Tag.

Was unverändert bleibt

Die Entrypoints und deren HTTP-zu-HTTPS-Redirect, die ACME-Resolver mit beiden Challenge-Typen, exposedByDefault, die Router- und Service-Labels, loadbalancer.server.port sowie das Dashboard funktionieren in v3 genauso wie in v2. Ihre Zertifikate werden ebenfalls übernommen, da v3 weiterhin die von v2 geschriebenen acme.json ausliest. Erstellen Sie dennoch eine Sicherungskopie der Datei, bevor Sie beginnen. Ein Rollback, bei dem diese Datei verloren geht, führt direkt zum Let's Encrypt Duplicate-Certificate-Rate-Limit:

cp ./letsencrypt/acme.json ./letsencrypt/acme.json.v2-backup

Der Migrationspfad

Schritt 1: Fixieren Sie die aktuelle Version. Ändern Sie jedes traefik:latest oder traefik:v2 Tag in die exakte Version, die Sie aktuell nutzen, zum Beispiel traefik:v2.11, und committen Sie das gesamte compose Verzeichnis in git. Jeder spätere Schritt ist durch einen checkout rückgängig zu machen. Falls das Neuerstellen eines einzelnen Services mit docker compose up -d <service> noch nicht Routine ist, erklärt der Docker Compose Grundlagen Guide die für diese Migration relevanten Operationen.

Schritt 2: Bereinigen Sie die statische Konfiguration und aktivieren Sie den Kompatibilitätsmodus. Entfernen Sie alle Optionen, die in v3 entfernt wurden (pilot, swarmMode, tls.caOptional, experimental.http3), und weisen Sie v3 an, Regeln standardmäßig als v2 Syntax zu behandeln. In traefik.yml:

core:
  defaultRuleSyntax: v2

Oder als Flag in der compose command: Liste: --core.defaultRuleSyntax=v2. Der Kompatibilitätsmodus gilt nur für die Syntax der Regeln. Er stellt keine entfernten Optionen wieder her und benennt Middlewares nicht automatisch um.

Schritt 3: Bereiten Sie die Umbenennung der Middlewares vor. Suchen Sie in Ihren compose Dateien nach den alten Namen: grep -rn ipwhitelist docker-compose*.yml. Ändern Sie jedes ipwhitelist Label in ipallowlist, aber wenden Sie die Änderung noch nicht an, da der neue Name in v2 nicht existiert. Diese Änderungen werden zusammen mit dem Wechsel im nächsten Schritt übernommen. (Falls ein Eintrag übersehen wird, akzeptiert die aktuelle v3 den alten Namen noch als deprecated Alias, sodass die Liste weiterhin funktioniert; korrigieren Sie dies beim nächsten Durchlauf, anstatt um 2 Uhr morgens.)

Schritt 4: Ändern Sie das Image-Tag. Setzen Sie das Traefik Image auf die aktuelle v3 Version, zum Zeitpunkt der Erstellung traefik:v3.5, und führen Sie dann aus:

docker compose up -d
docker compose logs -f traefik

Da der Kompatibilitätsmodus aktiviert ist, passen Ihre v2 Regeln weiterhin. Da up -d zudem die Services neu erstellt hat, deren Middleware-Labels Sie umbenannt haben, starten diese Router fehlerfrei. Ein korrekter Log enthält keine field not found Zeile und keine does not exist Zeile.

Seien Sie sich über das Zeitfenster bewusst, das dieser Schritt öffnet. Ein Router, der auf einen Middleware-Namen verweist, den v3 nicht kennt (Tippfehler oder entfernte Option), ist offline, sobald das neue Traefik startet, bis sein App-Container neu erstellt wurde. Auf einem einzelnen Host benötigt docker compose up -d dafür nur wenige Sekunden. Wenn eine Route absolut nicht unterbrochen werden darf, entfernen Sie die umbenannte Middleware aus dem middlewares Label dieses Routers vor dem Wechsel und fügen Sie sie danach wieder hinzu. Entscheiden Sie im Vorfeld, ob diese Route für die dazwischenliegende Minute ohne ihre IP-Allowlist auskommen kann.

Schritt 5: Migrieren Sie Regeln Service für Service. Bearbeiten Sie einen App-Container nach dem anderen: Schreiben Sie dessen Regel in die v3 Syntax um, erstellen Sie nur diesen Service mit docker compose up -d app neu und testen Sie ihn, bevor Sie fortfahren. Falls ein Service eine Regel besitzt, die noch nicht umgeschrieben werden kann, versehen Sie diesen einzelnen Router mit dem Escape-Label traefik.http.routers.app.ruleSyntax=v2 und fahren Sie fort.

Schritt 6: Deaktivieren Sie den Kompatibilitätsmodus. Wenn alle Regeln in v3 Syntax vorliegen, löschen Sie defaultRuleSyntax und alle ruleSyntax Labels, starten Sie Traefik neu und prüfen Sie, ob jeder Router im Dashboard weiterhin grün angezeigt wird. Nutzen Sie den Kompatibilitätsmodus nicht dauerhaft: Traefik hat beide Optionen in v3.4 als deprecated markiert und wird sie in der nächsten Major-Version entfernen. Sie dienen als Brücke, nicht als Ziel.

Vorher und nachher: Labels eines Dienstes

Hier ist eine Applikation, die alle bekannten Änderungen gleichzeitig enthält: ein Multi-Value Host, einen PathPrefix-Platzhalter und eine ipWhiteList-Middleware. Der v2-Block:

  app:
    image: app:1.4
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - traefik.enable=true
      - traefik.http.routers.app.rule=Host(`app.example.com`,`www.example.com`) && PathPrefix(`/api/{version:v[0-9]+}`)
      - traefik.http.routers.app.entrypoints=websecure
      - traefik.http.routers.app.tls.certresolver=le
      - traefik.http.routers.app.middlewares=office
      - traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24
      - traefik.http.services.app.loadbalancer.server.port=8080

Und derselbe Dienst migriert auf v3:

  app:
    image: app:1.4
    restart: unless-stopped
    networks:
      - proxy
    labels:
      - traefik.enable=true
      - traefik.http.routers.app.rule=(Host(`app.example.com`) || Host(`www.example.com`)) && PathRegexp(`^/api/v[0-9]+`)
      - traefik.http.routers.app.entrypoints=websecure
      - traefik.http.routers.app.tls.certresolver=le
      - traefik.http.routers.app.middlewares=office
      - traefik.http.middlewares.office.ipallowlist.sourcerange=10.0.0.0/24
      - traefik.http.services.app.loadbalancer.server.port=8080

Zwei Labels wurden geändert. Die Regel hat ihr Multi-Value Host in zwei durch || verbundene Matcher aufgeteilt und den Platzhalter durch PathRegexp ersetzt; zudem wurde das Middleware-Label von ipwhitelist auf ipallowlist geändert. Der Entrypoint, der Certificate Resolver, die Verbindung vom Router zur Middleware und der Service-Port wurden nicht verändert.

Testen Sie jeden Dienst mit dem Dashboard

Öffnen Sie nach jeder Änderung die Seite HTTP routers im Dashboard. Jeder Router muss grün angezeigt werden. Ein Router mit einem Fehler-Badge gibt das genaue Problem an. Meistens ist es eine Middleware, die unter ihrem neuen Namen nicht existiert, oder eine Regel, die v3 nicht parsen kann. Überprüfen Sie dies anschließend von extern, einen Hostnamen nach dem anderen:

curl -sI https://app.example.com/api/v1/status

Ein 200 oder der normale Redirect Ihrer App bedeutet, dass sowohl das Routing als auch TLS funktionieren. Ein 404 von Traefik bedeutet, dass der Router nicht gestartet ist; kehren Sie zum Dashboard zurück und lesen Sie den Fehler. Lassen Sie docker compose logs -f traefik in einem zweiten Terminal offen, während Sie arbeiten, da jeder Parsing-Fehler sofort dort erscheint, sobald ein Container neu startet.

Rollback-Integrität

Behalten Sie die v2 compose file, die statische Konfiguration und das acme.json backup bei, bis jeder Service über v3 routet und erfolgreich getestet wurde. Ein Rollback erfolgt durch das Auschecken des Commits vor der Migration und das Ausführen von docker compose up -d. Dies muss die vollständige Datei sein und nicht nur das Image-Tag. v3-spezifische Labels sind unter v2 ungültig, genau wie v2-Labels unter v3 ungültig waren: ipallowlist existiert in v2 nicht und ein PathRegexp matcher kann dort nicht geparst werden. Falls acme.json während des Prozesses verloren gegangen ist oder beschädigt wurde, stellen Sie die Backup-Kopie wieder her, bevor Sie v2 starten. Dies verhindert, dass das Rollback das Let's Encrypt Rate-Limit durch die gleichzeitige Neuerstellung von fünf Zertifikaten erschöpft.

FAQ

Muss ich jede Router-Regel für Traefik v3 umschreiben?

Nein. Eine einfache Host(app.example.com)-Regel mit Backticks ist in beiden Versionen gültig; dies deckt die meisten Compose-Setups ab. Ein Umschreiben ist nur erforderlich, wenn eine Regel Funktionen verwendet, die nur in v2 verfügbar waren: Regex oder Platzhalter innerhalb von Path und PathPrefix, mehrere Hostnames innerhalb eines Host(), Anführungszeichen anstelle von Backticks oder die entfernten Matcher Headers, HeadersRegexp und HostHeader.

Was ist mit ipWhiteList in Traefik v3 passiert?

Es wurde in ipAllowList umbenannt, wobei die Konfiguration innerhalb unverändert bleibt. Ein v2-Label wie traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 wird also zu derselben Zeile mit ipallowlist. Aktuelle v3-Releases, einschließlich v3.5, akzeptieren den alten Namen noch als veralteten Alias. Ein nicht umbenanntes Label erzwingt die Allowlist daher weiterhin ohne Fehlermeldung. Betrachten Sie dies als temporäre Lösung und nicht als Grund, das Umbenennen zu ignorieren: Der Alias ist für die Entfernung geplant. Ein Middleware-Name, den Traefik nicht kennt, führt stattdessen zu einem Fehler mit einem Router-Error und einem 404. Das Dashboard zeigt den Fehler an, und Anfragen an diesen Hostnamen liefern einen 404-Fehler zurück.

Kann Traefik v3 noch v2-Regelsyntax lesen?

Ja. Setzen Sie core.defaultRuleSyntax: v2 in der statischen Konfiguration, um die v2-Syntax während der Migration als Standard beizubehalten. Nutzen Sie das ruleSyntax=v2-Label pro Router für einzelne Ausnahmen, nachdem Sie den Standard wieder umgestellt haben. Betrachten Sie beide als temporär: Traefik hat sie in v3.4 als veraltet markiert und wird sie in der nächsten Major-Version entfernen.

Überleben meine Let's Encrypt-Zertifikate das Upgrade?

Ja. Traefik v3 liest weiterhin die von v2 geschriebene acme.json-Datei. Zertifikate werden nicht neu ausgestellt, nur weil die Binary gewechselt wurde. Kopieren Sie die Datei dennoch sicherheitshalber an einen anderen Ort, bevor Sie beginnen. Ein Rollback oder ein gelöschtes Volume, das acme.json verliert, erzwingt eine gleichzeitige Neuausstellung aller Zertifikate. Let's Encrypt erlaubt nur fünf Duplikate pro Woche für denselben Satz von Hostnames.

Warum startet Traefik v3 nach dem Upgrade nicht?

Fast immer, weil die statische Konfiguration noch eine Option enthält, die in v3 entfernt wurde. Traefik verweigert den Start, wenn Optionen verwendet werden, die es nicht erkennt. Bei bekannten Überresten (pilot, providers.docker.swarmMode, experimental.http3) gibt das Log incompatible deprecated static option found aus und nennt den Verursacher. Bei Elementen, die Traefik noch nie gesehen hat, wie zum Beispiel tls.caOptional, erscheint field not found zusammen mit dem Knoten. Löschen oder ersetzen Sie jedes Element und starten Sie den Container anschließend neu.