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.

Die Umbenennungen und Entfernungen

• 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 genau seine bisherige Bedeutung. Aktuelle v3-Releases, einschließlich v3.5, akzeptieren den alten Namen weiterhin als veralteten Alias und erzwingen die Liste weiterhin. Diese eine Umbenennung legt beim Umschalten daher nichts lahm. Benennen Sie sie trotzdem um: Der Alias soll entfernt werden und verschwindet damit still aus der Liste der veralteten Optionen, statt später einen lauten Fehler zu verursachen.
• providers.docker.swarmMode=true ist entfallen. Swarm hat jetzt einen eigenen Provider, der als providers.swarm.endpoint konfiguriert wird.
• Der Abschnitt pilot ist vollständig entfallen.
• experimental.http3 ist entfallen. HTTP/3 wird direkt am Entrypoint aktiviert.
• tls.caOptional ist sowohl aus den Providern als auch aus der forwardAuth-Middleware entfallen. Wenn diese Middleware ein selbst gehostetes Authentik-SSO vorgelagert ist, besteht die gesamte Migration darin, die Zeile caOptional zu löschen. Die forwardAuth-Adresse, die vertrauenswürdigen Header und der dahinterliegende Outpost verhalten sich unter v3 unverändert.
• Der InfluxDB-v1-Metrikprovider, der Rancher-Provider und der Marathon-Provider sind entfallen.
• Das Tracing wurde auf OpenTelemetry umgestellt. Die dedizierten Tracing-Backends, darunter die Jaeger- und Zipkin-Integrationen, sind entfallen. v3 exportiert stattdessen OTLP, das OpenTelemetry-Protokoll.
• Die veralteten ssl*-Optionen innerhalb der Headers-Middleware (sslRedirect, sslHost und die übrigen) sind entfallen. 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 unbekannte Option enthält. Eine verbliebene Zeile pilot oder swarmMode beendet den Container beim Start mit einer incompatible deprecated static option found-Meldung, die den verbliebenen Eintrag nennt. Eine Option, die Traefik überhaupt nicht kennt (ein Tippfehler oder tls.caOptional), führt stattdessen zu field not found. Bereinigen Sie die statische Konfiguration, bevor Sie den Image-Tag ändern.

Ein Middleware-Name, den Traefik tatsächlich nicht kennt (ein Tippfehler oder ein Name, der entfernt und nicht durch einen Alias ersetzt wurde), führt zu einem anderen Fehler: Der Router, der darauf verweist, wird mit einem Fehler statt mit einer Route geladen, das Dashboard kennzeichnet 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-Versionen NICHT zu dieser Kategorie gehört: Der Name bleibt als veralteter Alias erhalten. Ein nicht umbenanntes Label funktioniert daher weiterhin unbemerkt.

Die Syntax der Regeln ändert sich

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

• Werte innerhalb von Matchern müssen mit Backticks eingeschlossen werden. v2 akzeptierte auch doppelte Anführungszeichen; v3 nicht. Aus Host("app.example.com") muss daher Host(app.example.com) werden.
• 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 in einen PathRegexp-Matcher mit der Syntax regulärer Go-Ausdrücke umgewandelt werden.
• Matcher akzeptieren jetzt nur noch einen Wert. In v2 war Host(app.example.com,www.example.com) zulässig; 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, das in v3 dasselbe abgleicht.
• Zwei Matcher sind neu: QueryRegexp sowie ClientIP, um die Clientadresse innerhalb einer Regel abzugleichen.

Die gute Nachricht: Eine einfache Host(app.example.com)-Regel mit Backticks ist bereits eine gültige v3-Syntax. 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

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 heute ausgeführt wird. Ändern Sie jedes traefik:latest- oder traefik:v2-Tag in die genaue Version, die Sie aktuell verwenden, beispielsweise traefik:v2.11, und übertragen Sie das gesamte Compose-Verzeichnis in git. Jeder spätere Schritt lässt sich dann mit einem checkout rückgängig machen. Falls das erneute Erstellen eines einzelnen Dienstes mit docker compose up -d <service> noch nicht selbstverständlich ist, beschreibt 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 alle von v3 entfernten Optionen (pilot, swarmMode, tls.caOptional, experimental.http3), und 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 betrifft nur die Regelsyntax. Er stellt entfernte Optionen nicht 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, wenden Sie die Änderung aber noch nicht an, weil der neue Name in v2 nicht existiert. Diese Änderungen werden zusammen mit dem Wechsel im nächsten Schritt ausgerollt. (Falls ein Eintrag durchrutscht, akzeptiert das aktuelle v3 den alten Namen weiterhin als veralteten Alias, sodass die Liste weiterhin durchgesetzt wird. Beheben Sie den Eintrag im nächsten Durchlauf und nicht um 2 Uhr morgens.)

Schritt 4: Wechseln Sie den Image-Tag. Setzen Sie das Traefik-Image auf die aktuelle v3-Version, zum Zeitpunkt der Erstellung dieses Textes traefik:v3.5, und führen Sie anschließend Folgendes aus:

docker compose up -d
docker compose logs -f traefik

Da der Kompatibilitätsmodus aktiviert ist, greifen Ihre v2-Regeln weiterhin. Da up -d außerdem die Dienste mit den umbenannten Middleware-Labels neu erstellt hat, starten die Router fehlerfrei. Ein fehlerfreies 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, beispielsweise wegen eines Tippfehlers oder einer entfernten Option, ist ab dem Start des neuen Traefik nicht verfügbar, bis sein Anwendungskontainer neu erstellt wurde. Auf einem einzelnen Server benötigt docker compose up -d dafür nur wenige Sekunden, um die Liste abzuarbeiten. Wenn eine Route wirklich ohne Unterbrechung verfügbar sein muss, entfernen Sie die umbenannte Middleware vor dem Wechsel aus dem middlewares-Label dieses Routers und fügen Sie sie danach wieder hinzu. Legen Sie vorher fest, ob diese Route in der Zwischenzeit für eine Minute ohne ihre IP-Allowlist auskommen kann.

Schritt 5: Migrieren Sie die Regeln dienstweise. 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 ein Dienst eine Regel enthält, die Sie noch nicht umschreiben können, 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 prüfen Sie, ob im Dashboard weiterhin alle Router grün angezeigt werden. 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 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.

Ehrlicher 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 wechseln Sie zum Commit vor der Migration und führen docker compose up -d aus. Dabei muss die gesamte Datei verwendet werden, nicht nur der Image-Tag. v3-spezifische Labels sind unter v2 aus demselben Grund falsch, aus dem v2-Labels unter v3 falsch waren: ipallowlist existiert in v2 nicht, und auch ein PathRegexp-Matcher kann dort nicht geparst werden. 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 es fünf Zertifikate gleichzeitig neu ausstellt.

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 nur erforderlich, wenn eine Regel v2-spezifische Funktionen verwendet hat: reguläre Ausdrücke oder Platzhalter innerhalb von Path und PathPrefix, mehrere Hostnamen innerhalb eines einzigen Host(), Anführungszeichen statt Backticks 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. Aktuelle v3-Releases, einschließlich v3.5, akzeptieren den alten Namen weiterhin als veralteten Alias. Ein nicht umbenanntes Label setzt die Allowlist daher weiterhin ohne sichtbare Meldung durch. Betrachten Sie das als Aufschub und nicht als Grund, die Umbenennung zu überspringen: Der Alias soll entfernt werden. Ein Middleware-Name, den Traefik tatsächlich nicht kennt, führt dagegen sofort zu einem Fehler, einem Router-Fehler und einer 404-Antwort. Das Dashboard zeigt den Fehler an. Anfragen an diesen Hostnamen liefern 404.

Kann Traefik v3 weiterhin die v2-Regelsyntax lesen?

Ja. Setzen Sie core.defaultRuleSyntax: v2 in der statischen Konfiguration, damit v2-Syntax während der Migration standardmäßig aktiv bleibt. Verwenden Sie nach der Rückstellung des Standards für einzelne verbliebene Router das routerbezogene ruleSyntax=v2-Label. 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 der geänderten Binärdatei neu ausgestellt. Kopieren Sie die Datei trotzdem vor Beginn der Arbeiten an einen sicheren Ort. Ein Rollback oder ein gelöschtes Volume, durch das acme.json verloren geht, erzwingt die erneute Ausstellung aller Zertifikate auf einmal. Let's Encrypt erlaubt für dieselbe Gruppe von Hostnamen jedoch nur fünf doppelte Zertifikate pro Woche.

Warum startet Traefik v3 nach dem Upgrade nicht?

Fast immer enthält die statische Konfiguration noch eine Option, die v3 entfernt hat. Traefik verweigert den Start, wenn die Konfiguration unbekannte Optionen enthält. Bei den bekannten verbliebenen Optionen (pilot, providers.docker.swarmMode, experimental.http3) meldet das Log incompatible deprecated static option found und nennt den Verursacher. Bei Optionen, die v3 nie unterstützt hat, wie tls.caOptional, meldet es field not found und nennt den Konfigurationsknoten. Löschen oder ersetzen Sie jede dieser Optionen. Starten Sie anschließend den Container erneut.