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.

Hernoemingen 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.5, accepteren de oude naam nog steeds als een deprecated alias en blijven de lijst afdwingen, dus deze hernoeming haalt niets onderuit. Hernoem het desondanks: de alias staat gepland voor verwijdering en verdwijnt geruisloos uit de deprecation-lijst.
• providers.docker.swarmMode=true is verwijderd. Swarm heeft nu een eigen provider, geconfigureerd als providers.swarm.endpoint.
• De sectie pilot is volledig verwijderd.
• experimental.http3 is verwijderd. HTTP/3 wordt nu 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, omdat het forwardAuth-adres, de vertrouwde headers en de outpost erachter op v3 hetzelfde werken.
• 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 integraties voor Jaeger en Zipkin, 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-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 het niet kent. Een achtergebleven regel pilot of swarmMode stopt de container bij het opstarten met een incompatible deprecated static option found-melding die de achtergebleven optie benoemt; een optie waar Traefik nog nooit van heeft gehoord (een typefout of tls.caOptional) stopt de container 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 op een andere manier: 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 NIET in deze categorie: het blijft bestaan als een deprecated alias, dus een niet-hernoemd label blijft gewoon werken.

De regelsyntaxis verandert

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

• Backticks zijn vereist 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 reguliere expressies of {id}-stijl placeholders meer. Een v2-regel zoals PathPrefix(/api/{version:v[0-9]+}) moet een PathRegexp-matcher worden, geschreven in Go-reguliere expressiesyntaxis.
• Matchers accepteren nu een enkele 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: QueryRegexp en ClientIP voor het matchen van het clientadres binnen een regel.

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

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: leg de huidige configuratie vast. 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 volgende stap is hierdoor ongedaan te maken met een checkout. Als het opnieuw aanmaken van een enkele service met docker compose up -d <service> nog niet vanzelfsprekend is, behandelt de basisgids voor Docker Compose de bewerkingen waarop deze migratie 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-syntaxis te behandelen. In traefik.yml:

core:
  defaultRuleSyntax: v2

Of als flag in de command:-lijst van de compose: --core.defaultRuleSyntax=v2. De compatibiliteitsmodus heeft alleen betrekking op de regelsyntaxis. Deze herstelt geen verwijderde opties en hernoemt geen middlewares voor u.

Stap 3: bereid de hernoeming van middlewares voor. Doorzoek uw compose-bestanden op de oude namen: grep -rn ipwhitelist docker-compose*.yml. Bewerk elk ipwhitelist-label naar ipallowlist, maar pas de wijziging nog niet toe, omdat de nieuwe naam in v2 nog niet bestaat. Deze wijzigingen worden tegelijk met de overstap in de volgende stap doorgevoerd. (Mocht er een ontsnappen, dan ondersteunt de huidige v3 de oude naam nog als een deprecated 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.5 op het moment van schrijven, en voer daarna uit:

docker compose up -d
docker compose logs -f traefik

Omdat de compatibiliteitsmodus is ingeschakeld, blijven uw v2-regels overeenkomen, en omdat up -d ook de services waarvan u de middleware-labels heeft hernoemd opnieuw heeft aangemaakt, starten die routers correct op. Een gezonde log bevat geen field not found-regel en geen does not exist-regel.

Wees realistisch over het tijdsvenster dat deze stap opent. 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 de app-container opnieuw is aangemaakt. Op één server zijn dit de enkele seconden die docker compose up -d nodig heeft om de lijst te verwerken. Als een route absoluut niet mag haperen, verwijder dan de hernoemde 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 IP-allowlist kan functioneren.

Stap 5: migreer regels per service. Werk één applicatie per keer af: herschrijf de regel naar v3-syntaxis, 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 de v3-syntaxis gebruikt, verwijdert u defaultRuleSyntax en eventuele ruleSyntax-labels, start u Traefik opnieuw op en bevestigt u dat elke router in het dashboard nog steeds groen wordt weergegeven. Blijf niet werken met de compatibiliteitsmodus ingeschakeld: Traefik heeft beide opties in v3.4 als deprecated gemarkeerd en verwijdert ze in de volgende grote versie; het is dus 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 van rollbacks

Behoud het v2 compose-bestand, de bijbehorende statische configuratie en de acme.json backup 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, niet enkel de image-tag, omdat labels die specifiek zijn voor v3 in v2 op precies dezelfde wijze onjuist zijn als v2-labels dat waren in v3: ipallowlist bestaat niet in v2 en een PathRegexp matcher zal daar evenmin worden geparseerd. Als acme.json tijdens het proces verloren is gegaan of beschadigd is, herstel dan de backup-kopie voordat u v2 start, zodat de rollback niet uw Let's Encrypt rate limit verbruikt door vijf certificaten tegelijk opnieuw uit te geven.

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 functies gebruikte die specifiek waren voor v2: regex of placeholders binnen Path en PathPrefix, meerdere hostnamen binnen één Host(), aanhalingstekens in plaats van backticks, 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 zelf ongewijzigd blijft. Een v2-label zoals traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 wordt dus dezelfde regel met ipallowlist erin. Huidige v3-releases, inclusief v3.5, accepteren de oude naam nog steeds als een deprecated alias. Een niet-hernoemd label blijft de allowlist dus geruisloos afdwingen. Beschouw dit als uitstel van executie in plaats van een reden om het hernoemen over te slaan: de alias staat gepland voor verwijdering. Een middleware-naam die Traefik echt niet kent, faalt luidruchtig met een routerfout en een 404. Het dashboard toont de fout en verzoeken naar 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 router-specifieke 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 door v2 is 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, en Let's Encrypt staat slechts vijf dubbele certificaten per week toe voor dezelfde set hostnamen.

Waarom start Traefik v3 niet na de upgrade?

Dit komt bijna altijd doordat 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) vermeldt het logboek incompatible deprecated static option found en noemt het de boosdoener. Voor alles wat v3 nooit heeft gekend, zoals tls.caOptional, geeft het field not found aan bij het betreffende knooppunt. Verwijder of vervang elk van deze en start de container vervolgens opnieuw.