Traefik v2 auf v3 migrieren: Was bricht?

Was ändert sich zwischen Traefik v2 und v3?

Die Migration von Traefik v2 auf v3 besteht größtenteils aus Umbenennungen. Die bekannteste Änderung ist, dass die Middleware ipWhiteList in ipAllowList umbenannt wurde. Darüber hinaus verschärft v3 die Syntax für Router-Regeln. PathPrefix unterstützt keine regulären Ausdrücke mehr. Mehrere Matcher wurden umbenannt oder entfernt. Einige Provider und Optionen entfallen vollständig. Alles andere funktioniert weiterhin: EntryPoints, die ACME-Zertifikatskonfiguration, der Workflow mit Docker-Labels und Ihre acme.json werden übernommen. v3 bietet außerdem einen Kompatibilitätsmodus, in dem die Regelsyntax von v2 weiterhin funktioniert. Sie können daher zuerst die Binärdatei aktualisieren und die Regeln anschließend Dienst für Dienst anpassen, statt alle Änderungen an einem riskanten Abend vorzunehmen.

Diese Anleitung setzt die labelbasierte Docker-Compose-Konfiguration aus der Anleitung zum Traefik-Reverse-Proxy voraus. Diese Seite verwendet v3 nativ. Die vorliegende Anleitung gilt für den Server, auf dem noch ein traefik:v2-Tag ausgeführt wird.

Umbenennungen und Entfernung

• ipWhiteList heißt jetzt ipAllowList, sowohl für die HTTP- als auch für die TCP-Middleware. Die darin enthaltenen Optionen bleiben unverändert, daher behält sourcerange exakt seine Bedeutung. Aktuelle v3-Releases, einschließlich v3.7, akzeptieren den alten Namen weiterhin als veralteten Alias und erzwingen die Liste weiterhin. Dabei protokollieren sie eine Warnung zur veralteten Bezeichnung. Diese eine Umbenennung legt beim Umschalten daher nichts lahm. Benennen Sie die Option trotzdem um: Der alte Name ist veraltet, und v2.11 versteht ipAllowList bereits. Die Umbenennung kann daher vor dem Upgrade aktiviert werden.
• providers.docker.swarmMode=true wurde entfernt. Swarm hat einen eigenen Provider, der als providers.swarm.endpoint konfiguriert wird.
• 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. Wenn diese Middleware ein selbst gehostetes Authentik-SSO vorgeschaltet hat, ist das Löschen der Zeile caOptional die vollständige Migration dafür. Die forwardAuth-Adresse, die vertrauenswürdigen Header und der dahinterliegende Outpost verhalten sich unter v3 weiterhin gleich.
• Der InfluxDB-v1-Metrikprovider, der Rancher-Provider und der Marathon-Provider wurden entfernt.
• Das Tracing wurde auf OpenTelemetry umgestellt. Die dedizierten Tracing-Backends, darunter die Jaeger- und Zipkin-Integrationen, wurden entfernt. v3 exportiert stattdessen OTLP, das OpenTelemetry-Protokoll.
• Die veralteten ssl*-Optionen innerhalb der Headers-Middleware (sslRedirect, sslHost und die übrigen) wurden entfernt. Entrypoint-Umleitungen und die redirectScheme-Middleware ersetzen sie.

Diese Entfernungen sind wichtiger, als es zunächst scheint. Traefik startet nicht, wenn die statische Konfiguration eine entfernte oder unbekannte Option enthält. Eine übrig gebliebene Zeile mit pilot, swarmMode, experimental.http3 oder dem Provider tls.caOptional stoppt den Container beim Booten. Traefik protokolliert zunächst eine Zeile mit der verbliebenen Option, beispielsweise, dass die Option tls.CAOptional des Docker-Providers in v3 entfernt wurde. Anschließend schlägt der Start mit incompatible deprecated install configuration option found fehl. Releases bis einschließlich v3.4 formulieren diese letzte Meldung als incompatible deprecated static option found. Eine Option, die Traefik schlicht nicht kennt, beispielsweise wegen eines Tippfehlers, stoppt den Start mit field not found; der Node bleibt stattdessen aus. Bereinigen Sie die statische Konfiguration, bevor Sie den Image-Tag ändern.

Ein Middleware-Name, den Traefik tatsächlich nicht kennt, beispielsweise wegen eines Tippfehlers oder weil der Name entfernt und nicht als Alias beibehalten wurde, führt zu einem anderen Fehler. Der Router, der auf diese Middleware verweist, wird mit einem Fehler statt mit einer Route geladen. Das Dashboard markiert ihn, und die API meldet middleware "offce@docker" does not exist. Anfragen an diesen Hostnamen erhalten den Status 404, weil der Router nicht gestartet wurde. Beachten Sie, dass ipwhitelist in aktuellen v3-Releases NICHT in diese Kategorie fällt: Der Name bleibt als veralteter Alias erhalten. Ein nicht umbenanntes Label funktioniert daher weiterhin ohne sichtbare Auswirkungen.

Die Regelsyntax ändert sich

In den Regeln findet die eigentliche Umschreibung statt. Die Änderungen in v3:

• Anführungszeichen gehören nicht dazu. Beide Versionen erwarten Regelwerte in Backticks oder maskierten doppelten Anführungszeichen und lehnen einfache Anführungszeichen ab. Daher bleiben Host(app.example.com) und ein Host("app.example.com") mit maskierten doppelten Anführungszeichen weiterhin gültig.
• PathPrefix unterstützt keine regulären Ausdrücke und keine Platzhalter im Stil von {id} mehr. Eine v2-Regel wie PathPrefix(/api/{version:v[0-9]+}) muss zu einem PathRegexp-Matcher werden, der die Syntax regulärer Go-Ausdrücke verwendet.
• Matcher akzeptieren jetzt genau einen Wert. v2 erlaubte Host(app.example.com,www.example.com); v3 erwartet Host(app.example.com) || Host(www.example.com). Ausnahmen sind Header, HeaderRegexp, Query und QueryRegexp. Diese akzeptieren weiterhin einen Namen und einen Wert.
• Headers und HeadersRegexp wurden in Header und HeaderRegexp umbenannt.
• HostHeader wurde entfernt. Verwenden Sie stattdessen Host. Dieser Matcher findet in v3 dasselbe.
• Zwei Matcher sind neu: PathRegexp und QueryRegexp. ClientIP zum Abgleichen der Clientadresse innerhalb einer Regel war bereits in v2.11 vorhanden und wird unverändert übernommen.

Die gute Nachricht: Eine einfache, mit Backticks geschriebene Host(app.example.com)-Regel ist bereits mit der v3-Syntax gültig. Die meisten kleinen Compose-Setups verwenden genau diese Form. Daher lassen sich die meisten Labels ohne Änderungen an den Regeln migrieren.

Prüfen Sie Ihre Labels, bevor Sie beginnen

Sie können den Umfang der Migration mit einer Suche ermitteln, weil jede inkompatible Änderung an einem Label ein Muster hinterlässt, das grep findet:

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. Keine Treffer bedeutet, dass Ihre Labels bereits gültige v3-Syntax verwenden und sich die Migration auf die statische Konfiguration sowie den Image-Tag beschränkt. Eine Bildschirmseite voller Treffer ist außerdem ein guter Zeitpunkt, um zu prüfen, ob dieser Proxy für den Server noch die richtige Wahl ist. Wie Traefik im Vergleich zu Nginx und Caddy abschneidet stellt diesen Überarbeitungsaufwand den Anforderungen gegenüber, die die beiden anderen für jede Anwendung an Sie stellen.

Was gleich bleibt

Entrypoints und ihre HTTP-zu-HTTPS-Weiterleitung, 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. Auch Ihre Zertifikate werden übernommen, weil v3 weiterhin die von v2 geschriebene acme.json einliest. Sichern Sie die Datei trotzdem, bevor Sie beginnen. Bei einem Rollback führt ein Verlust dieser Datei direkt zum Rate Limit von Let's Encrypt für doppelte Zertifikate:

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

Der Migrationspfad

Schritt 1: Fixieren Sie, was Sie heute ausführen. Ändern Sie jedes traefik:latest- oder traefik:v2-Tag in das genaue Release, das Sie verwenden, beispielsweise traefik:v2.11, und committen Sie das gesamte Compose-Verzeichnis in git. Jeder spätere Schritt lässt sich dann mit einem Checkout rückgängig machen. Wenn das Neuerstellen eines einzelnen Dienstes mit docker compose up -d <service> für Sie noch nicht selbstverständlich ist, behandelt die Einführung in die Docker-Compose-Grundlagen die für diese Migration erforderlichen Vorgänge.

Schritt 2: Bereinigen Sie die statische Konfiguration und aktivieren Sie den Kompatibilitätsmodus. Entfernen Sie alle von v3 entfernten Optionen (pilot, swarmMode, tls.caOptional, experimental.http3). Legen Sie anschließend fest, dass v3 Regeln standardmäßig als v2-Syntax behandelt. 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 Regelsyntax. Er stellt entfernte Optionen nicht wieder her und benennt Middlewares nicht automatisch um.

Schritt 3: Wenden Sie die Umbenennungen der Middlewares noch unter v2.11 an. Suchen Sie in Ihren Compose-Dateien nach den alten Namen: grep -rn ipwhitelist docker-compose*.yml. Ändern Sie jedes ipwhitelist-Label in ipallowlist und erstellen Sie diese Dienste mit docker compose up -d neu. v2.11 enthält bereits die IPAllowList-Middleware. Daher funktionieren die umbenannten Labels vor der Umstellung, und die Warnung zur Einstellung von IPWhiteList verschwindet aus Ihren v2-Logs. Releases älter als v2.11 kennen den neuen Namen nicht. Wenn Sie in Schritt 1 ein älteres v2 festgelegt haben, wechseln Sie zuerst zu traefik:v2.11. (Falls ein alter Name durchrutscht, akzeptiert das aktuelle v3 ihn weiterhin als veralteten Alias. Die Liste bleibt daher wirksam. Beheben Sie den Eintrag im nächsten Durchlauf und nicht um 2 Uhr morgens.)

Schritt 4: Wechseln Sie zum Image-Tag. Setzen Sie das Traefik-Image auf das aktuelle v3-Release, traefik:v3.7 (Stand: 11. Oktober 2026; v3.7.14 ist der aktuellste Patch), und führen Sie anschließend Folgendes aus:

docker compose up -d
docker compose logs -f traefik

Da der Kompatibilitätsmodus aktiviert ist, werden Ihre v2-Regeln weiterhin erkannt. Da die Umbenennungen der Middlewares bereits unter v2.11 aktiv waren, starten diese Router ohne Fehler. Ein gesundes Log enthält weder eine field not found-Zeile noch eine does not exist-Zeile.

Seien Sie sich über das Zeitfenster im Klaren, das dieser Schritt öffnet. Ein Router, der auf einen Middleware-Namen verweist, den v3 tatsächlich nicht kennt (etwa wegen eines Tippfehlers oder einer entfernten Option), ist ab dem Start des neuen Traefik bis zur Korrektur seiner Labels und dem Neuerstellen seines App-Containers nicht verfügbar. Wenn eine Route keinesfalls ausfallen darf, entfernen Sie die verdächtige Middleware vor der Umstellung aus dem middlewares-Label des Routers, fügen Sie sie danach wieder hinzu und entscheiden Sie vorher, ob die Route diese eine Minute ohne Middleware auskommen kann.

Schritt 5: Migrieren Sie die Regeln Dienst für Dienst. Bearbeiten Sie jeweils eine Anwendung: Schreiben Sie ihre Regel in die v3-Syntax um, erstellen Sie nur diesen Dienst mit docker compose up -d app neu und testen Sie ihn, bevor Sie fortfahren. Wenn eine Regel eines Dienstes noch nicht umgeschrieben werden kann, versehen Sie diesen einzelnen Router mit dem Ausweich-Label traefik.http.routers.app.ruleSyntax=v2 und arbeiten Sie weiter.

Schritt 6: Deaktivieren Sie den Kompatibilitätsmodus. Wenn jede Regel die v3-Syntax verwendet, löschen Sie defaultRuleSyntax und alle ruleSyntax-Labels, starten Sie Traefik neu und bestätigen Sie, dass weiterhin jeder Router im Dashboard grün angezeigt wird. Lassen Sie den Kompatibilitätsmodus nicht dauerhaft aktiviert. Traefik hat beide Optionen in v3.4 als veraltet markiert und entfernt sie in der nächsten Hauptversion. Sie sind daher eine Übergangslösung und kein dauerhaftes Ziel.

Vorher und nachher: die Labels eines Dienstes

Hier trägt eine Anwendung alle bekannten Änderungen gleichzeitig: ein mehrwertiges Host, ein 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 nach der Migration 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 teilte ihr mehrwertiges Host in zwei durch || verknüpfte Matcher auf und ersetzte den Platzhalter durch PathRegexp. Beim Middleware-Label wurde ipwhitelist durch ipallowlist ersetzt. Der Entrypoint, der Zertifikatsresolver, die Verknüpfung zwischen Router und Middleware sowie der Service-Port blieben unverändert.

Dienste mit dem Dashboard prüfen

Öffnen Sie nach jeder Änderung die Seite für HTTP-Router im Dashboard. Jeder Router sollte grün angezeigt werden. Ein Router mit einem Fehler-Badge nennt das konkrete Problem. In der Regel handelt es sich um eine Middleware, die unter ihrem neuen Namen nicht existiert, oder um eine Regel, die v3 nicht analysieren kann. Prüfen Sie anschließend von außerhalb, jeweils einen Hostnamen nach dem anderen:

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

Ein 200 oder die übliche Weiterleitung Ihrer Anwendung bedeutet, dass Routing und TLS weiterhin funktionieren. Ein 404 von Traefik bedeutet, dass der Router nicht gestartet wurde. Wechseln Sie zum Dashboard zurück und lesen Sie den dort angezeigten Fehler. Lassen Sie docker compose logs -f traefik in einem zweiten Terminal geöffnet, während Sie arbeiten. Jeder Analysefehler wird dort angezeigt, sobald ein Container neu gestartet wird.

Ehrlichkeit beim Rollback

Bewahren Sie die v2-Compose-Datei, ihre statische Konfiguration und das acme.json-Backup auf, bis jeder Dienst über v3 geroutet wird und unter realen Bedingungen getestet wurde. Für ein Rollback müssen Sie den Commit vor der Migration auschecken und docker compose up -d ausführen. Dabei muss die gesamte Datei verwendet werden, nicht nur der Image-Tag. Die v3-spezifische Syntax ist unter v2 aus demselben Grund ungültig, aus dem die v2-Syntax unter v3 ungültig war: Ein PathRegexp-Matcher lässt sich dort nicht parsen. Die umbenannten ipallowlist-Labels funktionieren unter v2.11, aber nicht unter einer älteren v2-Version. Diese kennt den neuen Namen nicht. Wenn acme.json auf dem Weg verloren gegangen oder beschädigt worden ist, stellen Sie vor dem Start von v2 die Backup-Kopie wieder her. Andernfalls verbraucht das Rollback Ihr Let's-Encrypt-Ratenlimit, weil fünf Zertifikate gleichzeitig neu ausgestellt werden.

FAQ

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

Nein. Eine einfache Host(app.example.com)-Regel mit Backticks ist in beiden Versionen gültig und deckt die meisten Compose-Setups ab. Eine Überarbeitung ist nur erforderlich, wenn eine Regel ausschließlich in v2 verfügbare Funktionen verwendet: reguläre Ausdrücke oder Platzhalter innerhalb von Path und PathPrefix, mehrere Hostnamen innerhalb eines einzelnen Host() oder die entfernten Matchers Headers, HeadersRegexp und HostHeader.

Was ist mit ipWhiteList in Traefik v3 passiert?

Der Name wurde in ipAllowList geändert. Die Konfiguration bleibt unverändert. Ein v2-Label wie traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 wird dadurch zu derselben Zeile mit ipallowlist darin. v2.11 akzeptiert den neuen Namen bereits, sodass Sie ihn vor dem Upgrade ändern können. Aktuelle v3-Releases, einschließlich v3.7, akzeptieren den alten Namen weiterhin als veralteten Alias. Ein nicht umbenanntes Label erzwingt die Allowlist daher weiterhin, schreibt aber eine Warnung ins Log. Betrachten Sie das als vorübergehende Übergangslösung und nicht als Grund, auf die Umbenennung zu verzichten: Veraltete Namen können in einem Release entfernt werden. Einen Middleware-Namen, den Traefik tatsächlich nicht kennt, weist Traefik dagegen mit einem Router-Fehler und einem 404 zurück. Das Dashboard zeigt den Fehler an, und Anfragen an diesen Hostnamen liefern 404 zurück.

Kann Traefik v3 weiterhin die v2-Regelsyntax lesen?

Ja. Setzen Sie core.defaultRuleSyntax: v2 in der statischen Konfiguration, damit während der Migration standardmäßig die v2-Syntax verwendet wird. Nachdem Sie den Standard wieder zurückgestellt haben, können Sie für einzelne verbleibende Router das Label ruleSyntax=v2 verwenden. Betrachten Sie beide Optionen als vorübergehend: Traefik hat sie in v3.4 als veraltet gekennzeichnet und entfernt sie in der nächsten Hauptversion.

Bleiben meine Let's Encrypt-Zertifikate nach dem Upgrade erhalten?

Ja. Traefik v3 liest weiterhin die Datei acme.json, die v2 geschrieben hat. Die Zertifikate werden daher nicht allein wegen der geänderten Binärdatei neu ausgestellt. Kopieren Sie die Datei trotzdem vor Beginn an einen sicheren Ort. Ein Rollback oder ein gelöschtes Volume, durch das acme.json verloren geht, erzwingt sonst die gleichzeitige Neuausstellung aller Zertifikate. Let's Encrypt erlaubt für dieselbe Menge von Hostnamen nur fünf doppelte Zertifikate pro Woche.

Warum startet Traefik v3 nach dem Upgrade nicht?

Fast immer liegt es daran, dass die statische Konfiguration noch eine von v3 entfernte Option enthält. Traefik verweigert den Start, wenn es eine Option nicht erkennt. Bei den bekannten verbliebenen Optionen (pilot, providers.docker.swarmMode, experimental.http3 und tls.caOptional der Provider) nennt das Log den Verursacher und meldet anschließend incompatible deprecated install configuration option found (bei v3.4 und früher incompatible deprecated static option found). Bei allem, was v3 nie bekannt war, beispielsweise einem Tippfehler, meldet es field not found zusammen mit dem betreffenden Knoten. Löschen oder ersetzen Sie jede dieser Optionen und starten Sie den Container anschließend erneut.