Traefik v2 naar v3 migratie: wat breekt er?

Wat verandert er tussen Traefik v2 en v3

Een migratie van Traefik v2 naar v3 is grotendeels een kwestie van hernoemen; de bekendste wijziging is dat de ipWhiteList-middleware is veranderd in ipAllowList. Daarnaast scherpt v3 de syntaxis voor routerregels aan (PathPrefix verliest zijn regex-functionaliteit, diverse matchers zijn hernoemd of verwijderd), verwijdert het enkele providers en opties volledig, en blijft de rest gewoon werken: entrypoints, de ACME-certificaatconfiguratie, de workflow met Docker-labels en uw acme.json blijven allemaal behouden. v3 bevat ook een compatibiliteitsmodus die de regel-syntaxis van v2 ondersteunt, zodat u eerst de binary kunt upgraden en de regels per service kunt herschrijven in plaats van alles in één risicovolle avond te moeten doen.

Deze handleiding gaat uit van de op Docker Compose gebaseerde configuratie met labels uit de handleiding voor de Traefik reverse proxy. Die pagina is native v3; deze pagina is bedoeld voor de server die nog op een traefik:v2-tag draait.

Naamswijzigingen en verwijderingen

• ipWhiteList is nu ipAllowList, voor zowel de HTTP- als de TCP-middleware. De opties daarbinnen zijn ongewijzigd, dus sourcerange behoudt zijn exacte betekenis. Huidige v3-releases, inclusief v3.7, accepteren de oude naam nog steeds als een deprecated alias en blijven de lijst afdwingen, waarbij een deprecation-waarschuwing wordt gelogd. Deze naamswijziging haalt dus niets offline. Hernoem het desondanks: de oude naam is deprecated en v2.11 begrijpt ipAllowList al, dus de naamswijziging kan live gaan vóór de upgrade.
• providers.docker.swarmMode=true is verwijderd. Swarm heeft zijn eigen provider, geconfigureerd als providers.swarm.endpoint.
• De sectie pilot is volledig verwijderd.
• experimental.http3 is verwijderd. HTTP/3 wordt direct op de entrypoint ingeschakeld.
• tls.caOptional is verwijderd uit de providers en uit de forwardAuth-middleware. Als die middleware voor een zelfgehoste Authentik SSO staat, is het verwijderen van de regel caOptional de volledige migratie daarvoor, omdat het forwardAuth-adres, de vertrouwde headers en de outpost erachter op v3 hetzelfde werken.
• De InfluxDB v1-metricsprovider, de Rancher-provider en de Marathon-provider zijn verwijderd.
• Tracing is verplaatst naar OpenTelemetry. De specifieke tracing-backends, waaronder de Jaeger- en Zipkin-integraties, zijn verwijderd en v3 exporteert in plaats daarvan OTLP (het OpenTelemetry-protocol).
• De deprecated ssl*-opties binnen de headers-middleware (sslRedirect, sslHost en de rest) zijn verwijderd. Entrypoint-omleidingen en de redirectScheme-middleware hebben deze vervangen.

Deze verwijderingen zijn belangrijker dan ze lijken, omdat Traefik weigert te starten wanneer de statische configuratie een optie bevat die is verwijderd of onbekend is. Een achtergebleven regel pilot, swarmMode, experimental.http3 of provider tls.caOptional stopt de container bij het opstarten: Traefik logt eerst een regel met de naam van het overblijfsel (bijvoorbeeld: Docker-provider tls.CAOptional-optie is verwijderd in v3) en faalt vervolgens met incompatible deprecated install configuration option found. Releases tot en met v3.4 verwoorden dat laatste bericht als incompatible deprecated static option found. Een optie waar Traefik nog nooit van heeft gehoord, zoals een typefout, stopt het proces in plaats daarvan met field not found. Schoon de statische configuratie op voordat u de image-tag wijzigt.

Een middleware-naam die Traefik echt niet kent (een typefout of een naam die is verwijderd in plaats van gealiast) faalt anders: de router die ernaar verwijst laadt met een fout in plaats van een route, het dashboard markeert dit en de API rapporteert middleware "offce@docker" does not exist. Verzoeken aan die hostnaam krijgen een 404 omdat de router nooit is opgestart. Let op: ipwhitelist valt in de huidige v3-versie NIET in deze categorie: het blijft bestaan als een deprecated alias, dus een niet-hernoemd label blijft geruisloos werken.

De regelsyntaxis wijzigt

Regels zijn de plek waar daadwerkelijke herschrijvingen plaatsvinden. De wijzigingen in v3:

• Quoting is hier geen onderdeel van. Beide versies accepteren regelwaarden tussen backticks of met geëscapete dubbele aanhalingstekens en wijzen enkele aanhalingstekens af, dus Host(app.example.com) en een geëscapete-dubbele-aanhalingsteken Host("app.example.com") blijven geldig zoals ze zijn.
• PathPrefix begrijpt geen reguliere expressies of {id}-stijl placeholders meer. Een v2-regel zoals PathPrefix(/api/{version:v[0-9]+}) moet een PathRegexp-matcher worden die is geschreven in de reguliere expressie-syntaxis van Go.
• Matchers accepteren nu één waarde. v2 stond Host(app.example.com,www.example.com) toe; v3 vereist Host(app.example.com) || Host(www.example.com). De uitzonderingen zijn Header, HeaderRegexp, Query en QueryRegexp, die nog steeds een naam plus een waarde accepteren.
• Headers en HeadersRegexp zijn hernoemd naar Header en HeaderRegexp.
• HostHeader is verwijderd. Gebruik Host, dat in v3 hetzelfde matcht.
• Er zijn twee nieuwe matchers: PathRegexp en QueryRegexp. ClientIP, voor het matchen van het clientadres binnen een regel, bestond al in v2.11 en blijft ongewijzigd.

Het goede nieuws: een eenvoudige Host(app.example.com)-regel geschreven met backticks is al geldige v3-syntaxis. De meeste kleine Compose-setups gebruiken precies dat, wat betekent dat de meeste labels zonder aanpassing van regels migreren.

Controleer uw labels voordat u begint

U kunt de omvang van uw migratie met één zoekopdracht bepalen, omdat elke ingrijpende wijziging in labels een patroon achterlaat dat met grep kan worden gevonden:

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

Elke treffer is één regel die moet worden bewerkt. ipwhitelist wordt ipallowlist. HostHeader wordt Host. Headers wordt Header. Een {...}-placeholder binnen PathPrefix wordt een PathRegexp-matcher. Een komma binnen Host() wordt twee Host()-matchers verbonden door ||. Nul treffers betekent dat uw labels al de geldige v3-syntaxis gebruiken en de migratie beperkt blijft tot de statische configuratie plus de image-tag. Een scherm vol treffers is ook een goed moment om u af te vragen of dit nog steeds de juiste proxy voor de server is, en hoe Traefik zich verhoudt tot Nginx en Caddy zet die herschrijfkosten af tegen wat de andere twee van u vragen per applicatie.

Wat blijft hetzelfde

Entrypoints en hun HTTP-naar-HTTPS-redirect, de ACME-resolvers met beide uitdagingstypen, exposedByDefault, de router- en service-labels, loadbalancer.server.port, en het dashboard werken in v3 op dezelfde manier als in v2. Uw certificaten blijven ook bruikbaar, omdat v3 het bestand acme.json blijft lezen dat door v2 is geschreven. Maak hoe dan ook een back-up van het bestand voordat u begint, aangezien een rollback waarbij dit bestand verloren gaat, direct leidt tot de rate limit voor dubbele certificaten van Let's Encrypt:

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

Het migratiepad

Stap 1: bevries de huidige configuratie. Wijzig elke traefik:latest of traefik:v2 tag naar de exacte release die u momenteel gebruikt, bijvoorbeeld traefik:v2.11, en commit de volledige compose-directory naar git. Elke latere stap is hiermee terug te draaien met een checkout. Als het opnieuw aanmaken van een enkele service met docker compose up -d <service> nog niet volledig vertrouwd is, behandelt de basisgids voor Docker Compose de bewerkingen waar deze migratie op leunt.

Stap 2: ruim de statische configuratie op en schakel de compatibiliteitsmodus in. Verwijder elke optie die in v3 is komen te vervallen (pilot, swarmMode, tls.caOptional, experimental.http3) en instrueer v3 vervolgens om regels standaard als v2-syntax te behandelen. In traefik.yml:

core:
  defaultRuleSyntax: v2

Of als flag in de compose command: lijst: --core.defaultRuleSyntax=v2. De compatibiliteitsmodus dekt alleen de regelsyntax. Het herstelt geen verwijderde opties en hernoemt middlewares niet voor u.

Stap 3: voer de hernoemingen van middlewares door terwijl u nog op v2.11 zit. Zoek in uw compose-bestanden naar de oude namen: grep -rn ipwhitelist docker-compose*.yml. Bewerk elk ipwhitelist label naar ipallowlist en maak die services opnieuw aan met docker compose up -d. v2.11 bevat al de IPAllowList middleware, dus de hernoemde labels werken vóór de overstap, en de waarschuwing voor de afschrijving van IPWhiteList verdwijnt uit uw v2-logs. Releases ouder dan v2.11 kennen de nieuwe naam niet; als u in stap 1 een oudere v2-versie heeft vastgezet, upgrade dan eerst naar traefik:v2.11. (Mocht er een ontsnappen, dan ondersteunt de huidige v3 de oude naam nog als een afgeschreven alias, zodat de lijst blijft werken; corrigeer dit in de volgende ronde in plaats van midden in de nacht.)

Stap 4: wijzig de image tag. Stel de Traefik image in op de huidige v3-release, traefik:v3.7 per 11 oktober 2026 (v3.7.14 is de nieuwste patch), en voer vervolgens uit:

docker compose up -d
docker compose logs -f traefik

Omdat de compatibiliteitsmodus is ingeschakeld, blijven uw v2-regels matchen, en omdat de hernoemingen van de middlewares al live zijn gegaan op v2.11, starten die routers foutloos op. Een gezonde log bevat geen field not found regel en geen does not exist regel.

Wees realistisch over het risico dat deze stap met zich meebrengt. Een router die verwijst naar een middleware-naam die v3 niet kent (door een typefout of een verwijderde optie) is offline vanaf het moment dat de nieuwe Traefik start totdat u de labels corrigeert en de app-container opnieuw aanmaakt. Als een route absoluut niet mag haperen, verwijder dan de betreffende middleware uit het middlewares label van die router vóór de overstap en voeg deze daarna weer toe. Bepaal vooraf of die route de minuut daartussen zonder de middleware kan.

Stap 5: migreer regels per service. Werk één applicatie per keer af: herschrijf de regel naar v3-syntax, maak alleen die service opnieuw aan met docker compose up -d app en test deze voordat u verdergaat. Als een service een regel heeft die u nog niet kunt herschrijven, geef die specifieke router dan het ontsnappingslabel traefik.http.routers.app.ruleSyntax=v2 en ga door.

Stap 6: schakel de compatibiliteitsmodus uit. Wanneer elke regel v3-syntax gebruikt, verwijdert u defaultRuleSyntax en eventuele ruleSyntax labels, start u Traefik opnieuw op en bevestigt u dat elke router nog steeds groen wordt weergegeven in het dashboard. Blijf niet werken met de compatibiliteitsmodus ingeschakeld: Traefik heeft beide opties in v3.4 afgeschreven en verwijdert ze in de volgende grote versie; het is een overbrugging, geen eindbestemming.

Voor en na: de labels van één service

Hier is een applicatie die alle bekende wijzigingen tegelijk bevat: een Host met meerdere waarden, een PathPrefix-placeholder en een ipWhiteList-middleware. Het v2-blok:

  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

En dezelfde service gemigreerd naar 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

Twee labels zijn gewijzigd. De regel heeft de Host met meerdere waarden gesplitst in twee matchers verbonden door || en de placeholder vervangen door PathRegexp, en het middleware-label heeft ipwhitelist ingewisseld voor ipallowlist. Het entrypoint, de certificate resolver, de router-naar-middleware-koppeling en de servicepoort zijn ongewijzigd gebleven.

Test elke service met het dashboard

Open na elke wijziging de pagina met HTTP-routers in het dashboard. Elke router hoort groen te zijn. Een router met een foutmelding geeft het exacte probleem aan; meestal is dit een middleware die niet bestaat onder de nieuwe naam of een regel die v3 niet kan parseren. Controleer daarna van buitenaf, één hostnaam per keer:

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

Een 200 of de normale redirect van uw app betekent dat zowel de routing als TLS correct werken. Een 404 van Traefik betekent dat de router niet is opgestart; ga terug naar het dashboard en lees de foutmelding. Houd docker compose logs -f traefik open in een tweede terminal terwijl u werkt, omdat elke parseerfout daar direct verschijnt op het moment dat een container herstart.

Integriteit bij een rollback

Behoud het v2 compose-bestand, de bijbehorende statische configuratie en de acme.json back-up totdat elke service via v3 wordt gerouteerd en in de praktijk is getest. Een rollback houdt in dat u de commit van vóór de migratie uitcheckt en docker compose up -d uitvoert. Dit moet het volledige bestand zijn en niet alleen de image-tag, omdat v3-specifieke syntax in v2 op precies dezelfde wijze onjuist is als v2-syntax in v3: een PathRegexp matcher zal daar niet worden geparseerd. De hernoemde ipallowlist labels werken in v2.11, maar niet in oudere v2-releases, die de nieuwe naam niet herkennen. Als acme.json tijdens het proces verloren is gegaan of beschadigd is, herstel dan de back-up voordat u v2 start. Zo voorkomt u dat de rollback uw Let's Encrypt rate limit verbruikt door vijf certificaten tegelijk opnieuw aan te vragen.

FAQ

Moet ik elke router-regel herschrijven voor Traefik v3?

Nee. Een standaard Host(app.example.com)-regel geschreven met backticks is geldig in beide versies, en dat dekt de meeste Compose-configuraties. Herschrijven is alleen nodig wanneer een regel v2-specifieke functies gebruikte: regex of placeholders binnen Path en PathPrefix, meerdere hostnamen binnen één Host(), of de verwijderde Headers, HeadersRegexp en HostHeader matchers.

Wat is er gebeurd met ipWhiteList in Traefik v3?

Deze is hernoemd naar ipAllowList, waarbij de configuratie ongewijzigd blijft. Een v2-label zoals traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 wordt dus dezelfde regel met ipallowlist erin. v2.11 accepteert de nieuwe naam al, dus u kunt hernoemen voordat u de upgrade uitvoert. Huidige v3-releases, inclusief v3.7, accepteren de oude naam nog steeds als een deprecated alias. Een niet-hernoemd label blijft de allowlist afdwingen, met enkel een waarschuwing in het logbestand. Beschouw dit als uitstel van executie in plaats van een reden om het hernoemen over te slaan: deprecated namen zijn de namen die een release kan verwijderen. Een middleware-naam die Traefik echt niet kent, faalt luidruchtig met een router-fout en een 404. Het dashboard toont de fout en verzoeken aan die hostnaam retourneren een 404.

Kan Traefik v3 nog steeds v2-regelsyntaxis lezen?

Ja. Stel core.defaultRuleSyntax: v2 in de statische configuratie in om v2-syntaxis als standaard te behouden terwijl u migreert, en gebruik het per-router ruleSyntax=v2 label voor individuele achterblijvers nadat u de standaardinstelling weer hebt teruggezet. Beschouw beide als tijdelijk: Traefik heeft ze in v3.4 als deprecated gemarkeerd en verwijdert ze in de volgende grote versie.

Blijven mijn Let's Encrypt-certificaten behouden na de upgrade?

Ja. Traefik v3 blijft het acme.json-bestand lezen dat v2 heeft geschreven, dus certificaten worden niet opnieuw uitgegeven enkel omdat het binaire bestand is gewijzigd. Kopieer het bestand hoe dan ook naar een veilige locatie voordat u begint. Een rollback of een verwijderd volume waardoor acme.json verloren gaat, dwingt namelijk een gelijktijdige heruitgifte van alle certificaten af. Let's Encrypt staat slechts vijf dubbele certificaten per week toe voor dezelfde set hostnamen.

Waarom start Traefik v3 niet na de upgrade?

Bijna altijd omdat de statische configuratie nog een optie bevat die in v3 is verwijderd; Traefik weigert te starten bij opties die het niet herkent. Voor de bekende restanten (pilot, providers.docker.swarmMode, experimental.http3 en de tls.caOptional van providers) benoemt het logbestand de boosdoener en vermeldt vervolgens incompatible deprecated install configuration option found (incompatible deprecated static option found in v3.4 en eerder). Voor alles wat v3 nooit heeft gekend, zoals een typefout, geeft het field not found aan met de node. Verwijder of vervang elk item en start de container opnieuw.