SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor

Traefik v2 auf v3 migrieren: Was bricht?

Traefik v3 startet mit swarmMode oder pilot in der statischen Konfiguration nicht. Beheben Sie den Fehler zur inkompatiblen, veralteten Option und migrieren Sie Regeln.

Was ändert sich zwischen Traefik v2 und v3?

Eine Migration von Traefik v2 auf v3 besteht größtenteils aus Umbenennungen. Die bekannteste Umbenennung betrifft die Middleware ipWhiteList, die zu ipAllowList wird. Darüber hinaus verschärft v3 die Syntax der Router-Regeln: PathPrefix verliert seine Regex-Funktionen, mehrere Matcher werden umbenannt oder entfernt, und einige Provider sowie Optionen entfallen vollständig. Entrypoints, der ACME-Zertifikatspeicher, der Workflow mit Docker-Labels und Ihr acme.json bleiben erhalten. Auch das Verhalten ändert sich an einigen Stellen: v3 erkennt Content-Type nicht mehr automatisch, wenn das Backend diese Angabe nicht liefert. Verwenden Sie die ContentType-Middleware, um dieses Verhalten wiederherzustellen. v3 enthält außerdem einen Kompatibilitätsmodus, in dem die v2-Regelsyntax weiterhin funktioniert. Dadurch können Sie zuerst die Binärdatei aktualisieren und die Regeln anschließend Dienst für Dienst anpassen, statt die Umstellung an einem riskanten Abend vollständig durchzuführen.

Diese Anleitung setzt das labelbasierte Docker-Compose-Setup aus der Anleitung zum Traefik-Reverse-Proxy voraus. Diese Seite verwendet v3 nativ. Die vorliegende Anleitung bezieht sich auf das System, auf dem noch ein traefik:v2-Tag ausgeführt wird.

Die Umbenennungen und entfernten Optionen

  • ipWhiteList heißt jetzt ipAllowList, sowohl für die HTTP- als auch für die TCP-Middleware. Die enthaltenen Optionen sind unverändert, daher behält sourcerange seine genaue Bedeutung. Aktuelle v3-Releases, einschließlich v3.7, akzeptieren den alten Namen weiterhin als veralteten Alias und setzen die Liste weiterhin durch. Sie protokollieren dafür eine Warnung zur veralteten Verwendung. Diese eine Umbenennung führt beim Wechsel daher nicht zu einem Ausfall. Benennen Sie sie 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 bereitstellt, löschen Sie die Zeile caOptional und prüfen Sie auch das Vertrauen in Header: v3.6.14 hat trustForwardHeader als veraltet markiert. Vertrauenswürdige Proxy-IP-Adressen werden über forwardedHeaders.trustedIPs des Entrypoints und trustForwardHeader=true an der Middleware konfiguriert.
  • Der InfluxDB-v1-Metrik-Provider, 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-Weiterleitungen und die redirectScheme-Middleware haben sie ersetzt.

Diese Entfernungen sind wichtiger, als es zunächst scheint, weil Traefik nicht startet, 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 Start: Traefik protokolliert zunächst eine Zeile mit dem Namen des verbliebenen Eintrags, beispielsweise, dass die Docker-Provider-Option tls.CAOptional in v3 entfernt wurde. Anschließend beendet es den Start mit incompatible deprecated install configuration option found. Releases bis einschließlich v3.4 formulieren diese letzte Meldung als incompatible deprecated static option found. Eine Option, die Traefik überhaupt nicht kennt, beispielsweise wegen eines Tippfehlers, beendet den Start stattdessen mit field not found und dem betreffenden Knoten. Diese Startfehler verhindern, dass Traefik selbst ausgeführt wird. Daher kann diese Instanz keinen HTTP-404-Fehler zurückgeben. 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 durch einen Alias ersetzt wurde, führt zu einem anderen Fehler: Der Router, der auf ihn 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 einen 404-Fehler, weil der Router nicht gestartet wurde. Beachten Sie, dass ipwhitelist in aktuellen v3-Versionen nicht in diese Kategorie fällt: Der Name bleibt als veralteter Alias erhalten. Ein nicht umbenanntes Label funktioniert daher weiterhin, erzeugt jedoch eine Warnung zur veralteten Verwendung.

Die Regelsyntax ändert sich

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

  • Die Anführungszeichen gehören nicht dazu. Beide Versionen akzeptieren Regelwerte in Backticks oder in 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 versteht 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 mit regulärer Ausdruckssyntax von Go werden.
  • 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). Die Ausnahmen sind Header, HeaderRegexp, Query und QueryRegexp. Diese akzeptieren einen Namen und einen Wert. Query akzeptiert außerdem nur einen Namen, um einen Parameter ohne Wert abzugleichen. Schreiben Sie v2 Query(foo=bar) als Query(foo,bar) um.
  • Headers und HeadersRegexp wurden in Header und HeaderRegexp umbenannt.
  • HostHeader wurde entfernt. Verwenden Sie Host. Dieser Matcher gleicht in v3 dasselbe ab.
  • Zwei Matcher sind neu: PathRegexp und QueryRegexp. ClientIP zum Abgleichen der Clientadresse innerhalb einer Regel gab es bereits in v2.11. Teilen Sie mehrere Adressen in separate Matcher auf und verbinden Sie diese mit ||.

Die gute Nachricht: Eine einfache Host(app.example.com)-Regel mit Backticks ist bereits mit der v3-Syntax kompatibel. Die meisten kleinen Compose-Setups verwenden genau diese Form. Daher müssen die meisten Labels ohne Änderungen an den Regeln migriert werden.

Prüfen Sie Ihre Labels, bevor Sie beginnen

Beginnen Sie mit dieser Suche, um den Umfang Ihrer Migration zu messen. Sie erfasst mehrere häufige Änderungen:

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

Jeder Treffer entspricht einer zu prüfenden 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 Host()-Matchern, die durch || verbunden sind. Keine Treffer beweisen nicht, dass Ihre Labels gültige v3-Syntax verwenden: Prüfen Sie außerdem HeadersRegexp, Platzhalter innerhalb von Path, benannte Regex-Gruppen innerhalb von HostRegexp, Query-Argumente aus v2 sowie andere Matcher mit mehreren Werten, einschließlich Regeln mit maskierten doppelten Anführungszeichen. Wenn der Bildschirm voller Treffer ist, sollten Sie außerdem prüfen, ob dies noch der richtige Proxy für den Server ist. Wie sich Traefik mit Nginx und Caddy vergleicht stellt den erforderlichen Umschreibungsaufwand den Anforderungen der beiden anderen pro Anwendung gegenüber.

Was gleich bleibt

Entrypoints und ihre Weiterleitung von HTTP auf HTTPS, die ACME-Resolver mit den Challenges HTTP-01, TLS-ALPN-01 und DNS-01, exposedByDefault, die Router- und Service-Labels, loadbalancer.server.port sowie das Dashboard funktionieren auch in v3. Bei DNS-01-Konfigurationen werden die bisherigen Optionen delayBeforeCheck und disablePropagationCheck unter dnsChallenge.propagation als delayBeforeChecks und disableChecks geführt. Ihre Zertifikate werden ebenfalls übernommen, weil v3 weiterhin die von v2 geschriebene acme.json einliest. Sichern Sie die Datei trotzdem, bevor Sie beginnen. Wenn sie verloren geht, kann eine erneute Ausstellung ausgelöst werden. Let’s Encrypt erlaubt innerhalb von sieben Tagen bis zu fünf Zertifikate für exakt dieselbe Menge von Identifikatoren. Ob dieses Limit erreicht wird, hängt von früheren Ausstellungen für die jeweilige Menge ab:

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

Der Migrationspfad

Schritt 1: Fixieren Sie, was heute ausgeführt wird. Ändern Sie jedes traefik:latest- oder traefik:v2-Tag in die installierte Patch-Version oder den Image-Digest, zum Beispiel in traefik:v2.11.60, wenn Sie diese Patch-Version ausführen, und committen Sie das gesamte Compose-Verzeichnis in Git. Jeder spätere Schritt lässt sich dadurch mit einem Checkout rückgängig machen. Wenn das erneute Erstellen eines einzelnen Dienstes mit docker compose up -d <service> für Sie noch nicht selbstverständlich ist, behandelt der Leitfaden zu den Docker-Compose-Grundlagen die für diese Migration benötigten Vorgänge.

Schritt 2: Bereinigen Sie die statische Konfiguration und aktivieren Sie den Kompatibilitätsmodus. Entfernen Sie jede von v3 entfernte Option (pilot, swarmMode, tls.caOptional, experimental.http3). Weisen Sie v3 anschließend 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 Regelsyntax. Er stellt keine entfernten Optionen 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 schon vor der Umstellung, und die Warnung zur Veraltung von IPWhiteList verschwindet aus Ihren v2-Logs. Releases älter als v2.11 kennen den neuen Namen nicht. Wenn Sie in Schritt 1 eine ältere v2-Version fixiert haben, wechseln Sie daher zuerst auf eine fixierte v2.11-Patch-Version. (Falls ein alter Name durchrutscht, akzeptiert das aktuelle v3 ihn weiterhin als veralteten Alias, sodass die Liste weiterhin greift. Beheben Sie ihn im nächsten Durchlauf und nicht um 2 Uhr morgens.)

Schritt 4: Wechseln Sie den Image-Tag. Setzen Sie das Traefik-Image auf traefik:v3.7.17, die Patch-Version, die am 31. Oktober 2026 für das offizielle v3.7-Image angegeben ist, und führen Sie anschließend Folgendes aus:

docker compose up -d
docker compose logs -f traefik

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

v3.7.17 führt außerdem ein Limit von 500 Request-Header-Werten für HTTP/1 und HTTP/2 ein. Größere Requests werden vor dem Routing mit 431 Request Header Fields Too Large abgewiesen. Erhöhen Sie die http.maxHeaderValueCount-Option des EntryPoints, wenn eine Anwendung mehr benötigt.

Seien Sie sich darüber im Klaren, welches Zeitfenster dieser Schritt öffnet. Ein Router, der auf einen Middleware-Namen verweist, den v3 tatsächlich nicht kennt (beispielsweise wegen eines Tippfehlers oder weil die Middleware entfernt wurde), ist ab dem Start des neuen Traefik bis zur Korrektur seiner Labels und dem erneuten Erstellen des Anwendungcontainers nicht verfügbar. Wenn eine Route keinesfalls ausfallen darf, entfernen Sie die verdächtige Middleware vor der Umstellung aus dem middlewares-Label dieses Routers und fügen Sie sie danach wieder hinzu. Legen Sie vorher fest, ob die Route die dazwischenliegende Minute ohne diese 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, fügen Sie traefik.http.routers.app.ruleSyntax=v3 hinzu, um die v2-Standardeinstellung für diesen Router zu überschreiben, erstellen Sie nur diesen Dienst mit docker compose up -d app neu und testen Sie ihn, bevor Sie fortfahren. Wenn ein Dienst eine Regel enthält, die Sie noch nicht umschreiben können, geben Sie diesem einzelnen Router mit dem Label traefik.http.routers.app.ruleSyntax=v2 eine Ausweichmöglichkeit 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 jeder Router im Dashboard weiterhin 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 dauerhafter Zustand.

Vorher und nachher: die Labels eines Dienstes

Hier verwendet eine Anwendung gleichzeitig alle bekannten Änderungen: ein mehrwertiges 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 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.ruleSyntax=v3
      - 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, eines wurde hinzugefügt. Die Regel teilte ihr mehrwertiges Host in zwei durch || verbundene Matcher auf und ersetzte den Platzhalter durch PathRegexp. Beim Middleware-Label wurde ipwhitelist durch ipallowlist ersetzt. Das hinzugefügte Label ruleSyntax=v3 setzt den Kompatibilitätsmodus bis Schritt 6 außer Kraft. Der Entrypoint, der Zertifikatsresolver, die Verknüpfung zwischen Router und Middleware sowie der Service-Port blieben unverändert.

Jeden Dienst mit dem Dashboard testen

Öffnen Sie nach jeder Umstellung die Seite für HTTP-Router im Dashboard. Jeder Router sollte grün angezeigt werden. Ein Router mit einem Fehler-Badge nennt das genaue Problem. Meist handelt es sich um eine Middleware, die unter ihrem neuen Namen nicht existiert, oder um eine Regel, die Traefik v3 nicht analysieren kann. Prüfen Sie anschließend jeden Hostnamen einzeln von außerhalb:

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

Ein 200 oder die normale Weiterleitung Ihrer Anwendung bedeutet, dass Routing und TLS weiterhin funktionieren. Ein 404 von Traefik bedeutet, dass kein Router zur Anfrage passte. Prüfen Sie im Dashboard auf Router-Fehler. Prüfen Sie anschließend Hostname, Pfad, Entrypoint und TLS-Konfiguration, auch wenn der Router grün angezeigt wird. Lassen Sie docker compose logs -f traefik während der Arbeit in einem zweiten Terminal geöffnet. Jeder Analysefehler wird dort sofort angezeigt, sobald ein Container neu startet.

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 checken Sie den Commit vor der Migration aus und führen docker compose up -d aus. Es 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. Keine ältere v2-Version kennt den neuen Namen. Wenn acme.json unterwegs verloren gegangen oder beschädigt worden ist, stellen Sie die Backup-Kopie wieder her, bevor Sie v2 starten. So vermeiden Sie eine unnötige Neuausstellung von Zertifikaten und das Risiko, das Let's-Encrypt-Limit für eine identische Menge von Bezeichnern zu erreichen.

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 Anpassung ist erforderlich, wenn eine Regel nur in v2 verfügbare Funktionen verwendet: reguläre Ausdrücke oder Platzhalter innerhalb von Path und PathPrefix, Matcher mit mehreren Werten, benannte Regex-Gruppen innerhalb von HostRegexp, Query-Argumente aus v2 oder die entfernten Matcher Headers, HeadersRegexp und HostHeader.

Was ist mit ipWhiteList in Traefik v3 passiert?

Der Name wurde in ipAllowList geändert. Die Konfiguration innerhalb des Matchers bleibt unverändert. Aus einem v2-Label wie traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 wird daher dieselbe 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, erzeugt aber eine Warnung im Log. Betrachten Sie das als aufgeschobene Arbeit und nicht als Grund, die Umbenennung auszulassen: Veraltete Namen kann ein Release entfernen. Einen Middleware-Namen, den Traefik tatsächlich nicht kennt, weist Traefik stattdessen mit einem Router-Fehler und einem 404 deutlich zurück. Das Dashboard zeigt den Fehler an, und Anfragen an diesen Hostnamen liefern 404 zurück.

Kann Traefik v3 weiterhin die Regelsyntax aus v2 lesen?

Ja. Setzen Sie core.defaultRuleSyntax: v2 in der statischen Konfiguration, damit während der Migration weiterhin die Syntax aus v2 als Standard verwendet wird. Nach der Umstellung des Standards 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 markiert 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. Zertifikate werden daher nicht allein wegen des geänderten Binaries 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, kann sonst eine erneute Ausstellung von Zertifikaten auslösen. Let's Encrypt erlaubt innerhalb von sieben Tagen bis zu fünf Zertifikate für exakt dieselbe Gruppe von Identifikatoren. Ob die erneute Ausstellung dieses Limit erreicht, hängt von früheren Ausstellungen für die jeweilige Gruppe ab.

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 startet bei Optionen, die es nicht erkennt, nicht. 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 älter incompatible deprecated static option found). Bei allem, was v3 nicht kennt, beispielsweise einem Tippfehler, meldet es field not found mit dem betreffenden Knoten. Löschen oder ersetzen Sie jede dieser Optionen und starten Sie den Container anschließend erneut.

War dieser Artikel hilfreich?