Traefik v2 naar v3 migratie: wat verandert er?

Wat verandert er tussen Traefik v2 en v3

Een migratie van Traefik v2 naar v3 bestaat voornamelijk uit het hernoemen van onderdelen. De bekendste wijziging is dat de ipWhiteList middleware ipAllowList wordt. Verder verbetert v3 de syntaxis van router rules (de PathPrefix verliest zijn regex-functies en verschillende matchers zijn hernoemd of verwijderd). Enkele providers en opties zijn volledig verwijderd. De rest blijft werken: entrypoints, de ACME-certificaatinstellingen, de Docker labels workflow en uw acme.json blijven behouden. v3 bevat ook een compatibility mode die de v2 rule syntaxis ondersteunt. Hierdoor kunt u eerst de binary upgraden en de rules per service herschrijven in plaats van alles in één risicovolle avond.

Deze gids gaat uit van de label-gebaseerde Docker Compose setup uit de Traefik reverse proxy gids. Die pagina is v3-native; deze pagina is voor systemen die nog een traefik:v2 tag gebruiken.

De hernoemingen en verwijderingen

• ipWhiteList is nu ipAllowList, voor zowel de HTTP- als de TCP-middleware. De opties binnenin zijn ongewijzigd, dus sourcerange behoudt exact dezelfde betekenis. Huidige v3-releases, inclusief v3.5, accepteren de oude naam nog als een deprecated alias en handhaven de lijst. Deze hernoeming veroorzaakt dus geen problemen. Hernoem het toch: de alias wordt verwijderd en verdwijnt zonder melding uit de deprecation list.
• providers.docker.swarmMode=true is verwijderd. Swarm krijgt een eigen provider, geconfigureerd als providers.swarm.endpoint.
• De pilot sectie 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.
• De InfluxDB v1 metrics provider, 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. 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 redirections en de redirectScheme middleware hebben deze vervangen.

Deze verwijderingen zijn belangrijker dan ze lijken, omdat Traefik weigert te starten als de statische configuratie een onbekende optie bevat. Een achtergebleven pilot of swarmMode regel zorgt ervoor dat de container bij het opstarten stopt met een incompatible deprecated static option found melding die de resterende optie benoemt; een optie die Traefik niet kent (een typefout of tls.caOptional) zorgt voor een stop met field not found. Maak de statische configuratie schoon 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 een alias geworden) faalt anders: de router die ernaar verwijst wordt geladen met een fout in plaats van een route, het dashboard markeert deze, en de API rapporteert middleware "offce@docker" does not exist. Verzoeken naar die hostname geven een 404 omdat de router niet is opgestart. Let op: ipwhitelist valt in de huidige v3 niet in deze categorie; het blijft bestaan als een deprecated alias, waardoor een niet-hernoemde label stilzwijgend blijft werken.

De syntaxis van regels verandert

Regels zijn de plek waar de eigenlijke herschrijving plaatsvindt. De wijzigingen in v3:

• Backticks zijn verplicht rond waarden binnen matchers. v2 accepteerde ook dubbele aanhalingstekens; v3 doet dit niet, dus Host("app.example.com") moet Host(app.example.com) worden.
• PathPrefix begrijpt geen regular expressions of placeholders in {id}-stijl meer. Een v2 regel zoals PathPrefix(/api/{version:v[0-9]+}) moet een PathRegexp matcher worden geschreven in Go regular expression syntaxis.
• Matchers accepteren nu slechts éé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; deze accepteren nog steeds een naam plus een waarde.
• Headers en HeadersRegexp zijn hernoemd naar Header en HeaderRegexp.
• HostHeader is verwijderd. Gebruik Host, wat in v3 hetzelfde matcht.
• Twee matchers zijn nieuw: QueryRegexp en ClientIP voor het matchen van het client-adres binnen een regel.

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

Controleer uw labels voordat u begint

U kunt de omvang van uw migratie met één zoekopdracht bepalen. Elke wijziging in een kritiek label laat een patroon achter dat met grep gevonden kan worden:

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

Elke match komt overeen met één regel die bewerkt moet worden. 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 die verbonden zijn door ||. Nul resultaten betekent dat uw labels al voldoen aan de v3 syntax. In dat geval beperkt de migratie zich tot de statische configuratie plus de image tag.

Wat gelijk blijft

Entrypoints en de HTTP-naar-HTTPS redirect, de ACME-resolvers met beide challenge-types, exposedByDefault, de router- en service-labels, loadbalancer.server.port en het dashboard werken in v3 zoals in v2. Uw certificaten blijven behouden, omdat v3 de acme.json blijft lezen die door v2 is geschreven. Maak toch een back-up van het bestand voordat u begint. Een rollback waarbij dit bestand verloren gaat, leidt direct tot de Let's Encrypt duplicate-certificate rate limit:

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

Het migratiepad

Stap 1: leg vast wat u momenteel uitvoert. Wijzig elke traefik:latest of traefik:v2 tag naar de exacte release die u gebruikt, bijvoorbeeld traefik:v2.11, en commit de volledige compose-directory naar git. Elke volgende stap is hiermee ongedaan te maken met een checkout. Als het opnieuw maken van een enkele service met docker compose up -d <service> nog niet vanzelfsprekend is, dan behandelt de Docker Compose basics guide de operaties waarop deze migratie is gebaseerd.

Stap 2: maak de statische configuratie schoon en schakel de compatibiliteitsmodus in. Verwijder alle opties die in v3 zijn verwijderd (pilot, swarmMode, tls.caOptional, experimental.http3), en stel v3 vervolgens zo in dat regels standaard als v2-syntax worden behandeld. In traefik.yml:

core:
  defaultRuleSyntax: v2

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

Stap 3: bereid de hernoemde middlewares voor. Zoek in uw compose-bestanden naar de oude namen: grep -rn ipwhitelist docker-compose*.yml. Wijzig elk ipwhitelist label naar ipallowlist, maar pas de wijziging nog niet toe. De nieuwe naam bestaat namelijk nog niet in v2. Deze wijzigingen worden tegelijkertijd met de omschakeling in de volgende stap toegepast. (Als er een fout insluipt, accepteert de huidige v3 de oude naam nog als een deprecated alias, dus de lijst blijft werken; herstel dit in de volgende ronde in plaats van om 2 uur 's nachts.)

Stap 4: wijzig de image tag. Stel de Traefik image in op de huidige v3 release, traefik:v3.5 op het moment van schrijven, en voer vervolgens uit:

docker compose up -d
docker compose logs -f traefik

Omdat de compatibiliteitsmodus aan staat, blijven uw v2-regels werken. Omdat up -d ook de services heeft opnieuw aangemaakt waarvan u de middleware-labels heeft hernoemd, starten die routers correct op. Een correct logbestand bevat geen field not found regel en geen does not exist regel.

Wees realistisch over de tijdsperiode die deze stap creëert. 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 tot het moment dat de app-container opnieuw wordt aangemaakt. Op één machine duurt dit de paar seconden die docker compose up -d nodig heeft om de lijst te verwerken. Als een route absoluut niet mag uitvallen, verwijder dan de hernoemde middleware uit het middlewares label van die router vóór de omschakeling en voeg deze er daarna weer aan toe. Beslis vooraf of die route een minuut zonder de IP allow list kan functioneren.

Stap 5: migreer regels per service. Werk één app tegelijk 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 escape hatch label traefik.http.routers.app.ruleSyntax=v2 en ga verder.

Stap 6: schakel de compatibiliteitsmodus uit. Wanneer elke regel v3-syntax gebruikt, verwijder dan defaultRuleSyntax en alle ruleSyntax labels, herstart Traefik, en controleer of elke router nog steeds groen aangeeft in het dashboard. Gebruik de compatibiliteitsmodus niet permanent: Traefik heeft beide opties in v3.4 als deprecated gemarkeerd en verwijdert ze in de volgende major versie. Ze dienen als brug, niet als eindbestemming.

Voor en na: de labels van één service

Hier is een applicatie met alle bekende wijzigingen tegelijk: een multi-value Host, 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 splitste de multi-value Host in twee matchers die verbonden zijn door ||. De placeholder is vervangen door PathRegexp. Het middleware-label heeft ipwhitelist vervangen door ipallowlist. De entrypoint, de certificate resolver, de router-to-middleware verbinding en de service port zijn niet gewijzigd.

Test elke service met het dashboard

Open na elke wijziging de pagina HTTP routers van het dashboard. Elke router moet groen zijn. Een router met een foutmelding geeft de exacte oorzaak aan. Dit is meestal een middleware die onder de nieuwe naam niet bestaat, of een regel die v3 niet kan verwerken. Controleer vervolgens extern, één hostname tegelijk:

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 om de foutmelding te lezen. Houd docker compose logs -f traefik open in een tweede terminal tijdens het werk, omdat elke parsingfout daar verschijnt zodra een container herstart.

Rollback honesty

Behoud het v2 compose file, de statische configuratie en de acme.json backup totdat elke service via v3 routeert en volledig is getest. Een rollback uitvoeren betekent de commit van vóór de migratie uitchecken en docker compose up -d uitvoeren. Gebruik hiervoor het volledige bestand en niet alleen de image tag. v3-only labels zijn onjuist onder v2, op exact dezelfde manier als v2 labels onjuist waren onder v3: ipallowlist bestaat niet in v2, en een PathRegexp matcher kan daar ook niet worden verwerkt. Als acme.json tijdens het proces verloren is gegaan of beschadigd is geraakt, herstel dan de back-up kopie voordat u met v2 start. Zo voorkomt u dat de rollback uw Let's Encrypt rate limit verbruikt door vijf certificaten tegelijk opnieuw uit te geven.

FAQ

Moet ik elke routerregel herschrijven voor Traefik v3?

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

Wat is er gebeurd met ipWhiteList in Traefik v3?

Deze is hernoemd naar ipAllowList. De configuratie binnen de regel blijft ongewijzigd. Een v2 label zoals traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 wordt dus dezelfde regel met ipallowlist erin. Huidige v3-versies, inclusief v3.5, accepteren de oude naam nog als een deprecated alias. Een niet-hernoemde label blijft de allowlist dus stilzwijgend afdwingen. Beschouw dit als een tijdelijke oplossing in plaats van een reden om de hernoeming over te slaan: de alias wordt verwijderd. Een middleware-naam die Traefik niet kent, veroorzaakt een foutmelding met een router error en een 404. Het dashboard toont de fout en verzoeken naar die hostname geven een 404.

Kan Traefik v3 nog steeds v2 regel-syntax lezen?

Ja. Stel core.defaultRuleSyntax: v2 in de static configuration in om v2-syntax als standaard te behouden tijdens de migratie. Gebruik het ruleSyntax=v2 label per router voor individuele uitzonderingen nadat u de standaard weer heeft teruggezet. Beschouw beide als tijdelijk: Traefik heeft ze in v3.4 als deprecated gemarkeerd en verwijdert ze in de volgende major versie.

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

Ja. Traefik v3 blijft het acme.json bestand lezen dat door v2 is geschreven. Certificaten worden niet opnieuw uitgegeven enkel omdat de binary is gewijzigd. Kopieer het bestand naar een veilige locatie voordat u begint. Een rollback of een verwijderde volume waardoor acme.json verloren gaat, dwingt namelijk af dat elk certificaat tegelijkertijd opnieuw wordt uitgegeven. Let's Encrypt staat slechts vijf duplicaten per week toe voor dezelfde set hostnames.

Waarom start Traefik v3 niet na de upgrade?

Dit komt bijna altijd doordat de static configuration nog een optie bevat die door v3 is verwijderd. Traefik weigert te starten als er opties worden gebruikt die niet worden herkend. Voor bekende restanten (pilot, providers.docker.swarmMode, experimental.http3) vermeldt het logboek incompatible deprecated static option found en de oorzaak; voor zaken die v3 niet kent, zoals tls.caOptional, vermeldt het field not found met de betreffende node. Verwijder of vervang elke optie en start de container opnieuw.