Traefik v2 to v3 migration guide

Ano ang mga pagbabago mula Traefik v2 patungong v3

Ang migration mula Traefik v2 patungong v3 ay karaniwang pagpapalit lamang ng mga pangalan. Ang pinakasikat na pagbabago ay ang pagpapalit ng ipWhiteList middleware tungo sa ipAllowList. Bukod dito, mas mahigpit na ang syntax ng router rule sa v3 (nawala ang regex features ng PathPrefix, ang ilang matchers ay pinalitan o tinanggal), tinanggal ang ilang providers at options, ngunit mananatiling gumagana ang lahat ng iba pa: ang mga entrypoints, ang ACME certificate setup, ang Docker labels workflow, at ang iyong acme.json ay tuloy-tuloy pa rin. May kasama ring compatibility mode ang v3 para manatiling gumagana ang v2 rule syntax. Dahil dito, maaari mo munang i-upgrade ang binary at i-rewrite ang mga rule nang paisa-isang service sa halip na gawin ang lahat sa isang mabilisang gabi.

Ipinapalagay ng gabay na ito na gamit mo ang label-based Docker Compose setup mula sa traefik reverse proxy guide. Ang pahinang iyon ay v3-native; ang pahinang ito ay para sa mga system na gumagamit pa rin ng traefik:v2 tag.

Ang mga renames at removals

• Ang ipWhiteList ay ipAllowList na ngayon, para sa HTTP at TCP middleware. Walang nagbago sa mga options sa loob nito, kaya ang sourcerange ay may parehong kahulugan pa rin. Ang mga kasalukuyang v3 release, kasama ang v3.5, ay tinatanggap pa rin ang lumang pangalan bilang deprecated alias at patuloy na ipinapatupad ang listahan, kaya hindi makakaapekto ang rename na ito sa operasyon. I-rename pa rin ito: nakaplano nang tanggalin ang alias, at mawawala ito sa deprecation list nang tahimik.
• Wala na ang providers.docker.swarmMode=true. May sarili nang provider ang Swarm na naka-configure bilang providers.swarm.endpoint.
• Burado na ang pilot section.
• Wala na ang experimental.http3. Ang HTTP/3 ay naka-enable na nang direkta sa entrypoint.
• Wala na ang tls.caOptional sa mga providers at sa forwardAuth middleware.
• Wala na ang InfluxDB v1 metrics provider, ang Rancher provider, at ang Marathon provider.
• Lumipat ang tracing sa OpenTelemetry. Wala na ang mga dedicated tracing backend, kabilang ang Jaeger at Zipkin integrations; sa halip, OTLP (ang OpenTelemetry protocol) ang ine-export ng v3.
• Wala na ang mga deprecated na ssl* options sa loob ng headers middleware (sslRedirect, sslHost, at iba pa). Pinalitan ang mga ito ng entrypoint redirections at ng redirectScheme middleware.

Mahalaga ang mga pagtatanggal na ito dahil hindi magsisimula ang Traefik kapag ang static configuration nito ay may option na hindi nito kilala. Ang naiwang pilot o swarmMode na linya ay magpapatigil sa container sa boot na may incompatible deprecated static option found message na nagsasaad ng naiwang option; ang option na hindi kailanman narinig ng Traefik (isang typo, o tls.caOptional) ay magpapatigil dito na may field not found naman. Linisin ang static configuration bago palitan ang image tag.

Ang middleware name na hindi talaga kilala ng Traefik (isang typo, o pangalang tinanggal sa halip na ginawang alias) ay nagkakaroon ng ibang error: ang router na tumutukoy dito ay maglo-load na may error sa halip na isang route, mamamarkahan ito ng dashboard, at mag-uulat ang API ng middleware "offce@docker" does not exist. Ang mga request sa hostname na iyon ay makakakuha ng 404 dahil hindi nag-load ang router. Tandaan na ang ipwhitelist ay HINDI kabilang sa kategoryang ito sa kasalukuyang v3: nananatili ito bilang isang deprecated alias, kaya ang hindi pa na-rename na label ay patuloy na gagana nang tahimik.

Pagbabago sa syntax ng rule

Dito nagaganap ang mga tunay na rewriting. Ang mga pagbabago sa v3:

• Kailangan ang backticks sa mga value sa loob ng mga matcher. Tinatanggap ng v2 ang double quotes; hindi na ito tinatanggap sa v3, kaya ang Host("app.example.com") ay dapat maging Host(app.example.com).
• Hindi na naiintindihan ng PathPrefix ang regular expressions o ang mga placeholder na istilong {id}. Ang v2 rule na gaya ng PathPrefix(/api/{version:v[0-9]+}) ay dapat maging isang PathRegexp matcher na nakasulat sa Go regular expression syntax.
• Ang mga matcher ay tumatanggap na lamang ng iisang value. Pinapayagan ng v2 ang Host(app.example.com,www.example.com); ang v3 ay nangangailangan ng Host(app.example.com) || Host(www.example.com). Ang mga exception ay ang Header, HeaderRegexp, Query, at QueryRegexp, na tumatanggap pa rin ng pangalan plus value.
• Ang Headers at HeadersRegexp ay ni-rename sa Header at HeaderRegexp.
• Tinanggal ang HostHeader. Gamitin ang Host, na tumutugma sa parehong bagay sa v3.
• Dalawang bagong matcher: ang QueryRegexp, at ang ClientIP para sa pag-match ng client address sa loob ng isang rule.

Ang magandang balita: ang simpleng Host(app.example.com) rule na nakasulat gamit ang backticks ay valid na v3 syntax na. Karamihan sa mga maliliit na Compose setup ay gumagamit na nito, kaya ang karamihan sa mga label ay lilipat nang walang kailangang i-edit na rule.

I-audit ang iyong mga label bago magsimula

Maaari mong sukatin ang laki ng iyong migration gamit ang isang search. Ang bawat breaking label change ay nag-iiwan ng pattern na mahahanap ng grep:

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

Ang bawat hit ay isang linya na dapat i-edit. Ang ipwhitelist ay magiging ipallowlist. Ang HostHeader ay magiging Host. Ang Headers ay magiging Header. Ang isang {...} placeholder sa loob ng PathPrefix ay magiging isang PathRegexp matcher. Ang isang comma sa loob ng Host() ay magiging dalawang Host() matcher na pinagdugtong ng ||. Kung zero hits ang resulta, valid na ang iyong mga label para sa v3 syntax. Ang migration ay mababawasan na lamang sa static configuration at sa image tag.

Ano ang hindi nagbabago

Ang mga entrypoint at ang kanilang HTTP-to-HTTPS redirect, ang mga ACME resolver para sa dalawang challenge type, exposedByDefault, ang router at service labels, loadbalancer.server.port, at ang dashboard ay gagana sa v3 gaya ng sa v2. Ang iyong mga certificate ay madadala rin, dahil binabasa ng v3 ang acme.json na isinulat ng v2. I-back up pa rin ang file bago magsimula, dahil ang rollback na nagreresulta sa pagkawala nito ay direktang tatama sa Let's Encrypt duplicate-certificate rate limit:

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

Ang migration path

Step 1: i-pin ang ginagamit mo ngayon. Palitan ang anumang traefik:latest o traefik:v2 tag sa eksaktong release na gamit mo, halimbawa traefik:v2.11, at i-commit ang buong compose directory sa git. Ang bawat susunod na step ay maaaring i-reverse gamit ang checkout. Kung hindi ka pa sanay sa pag-recreate ng isang service gamit ang docker compose up -d <service>, ang Docker Compose basics guide ang nagpapaliwanag sa mga operasyong kailangan sa migration na ito.

Step 2: linisin ang static configuration at i-on ang compatibility mode. Alisin ang lahat ng option na tinanggal sa v3 (pilot, swarmMode, tls.caOptional, experimental.http3), pagkatapos ay i-set ang v3 na ituring ang mga rule bilang v2 syntax sa default. Sa traefik.yml:

core:
  defaultRuleSyntax: v2

O bilang flag sa compose command: list: --core.defaultRuleSyntax=v2. Ang compatibility mode ay para sa rule syntax lamang. Hindi nito ibabalik ang mga tinanggal na option, at hindi nito babaguhin ang mga pangalan ng middlewares para sa iyo.

Step 3: ihanda ang mga middleware renames. Hanapin sa iyong mga compose file ang mga lumang pangalan: grep -rn ipwhitelist docker-compose*.yml. I-edit ang bawat ipwhitelist label sa ipallowlist, pero huwag muna i-apply ang pagbabago dahil wala pa ang bagong pangalan sa v2. Ang mga edit na ito ay isasama sa pagpapalit sa susunod na step. (Kung may makalusot man, kinikilala pa rin ng kasalukuyang v3 ang lumang pangalan bilang deprecated alias, kaya patuloy ang pag-enforce sa listahan; ayusin ito sa susunod na pass sa halip na sa madaling araw.)

Step 4: palitan ang image tag. I-set ang Traefik image sa kasalukuyang v3 release, traefik:v3.5 sa oras ng pagsulat na ito, pagkatapos ay:

docker compose up -d
docker compose logs -f traefik

Dahil naka-on ang compatibility mode, patuloy na magma-match ang iyong mga v2 rules, at dahil muling ni-recreate ng up -d ang mga service kung saan binago mo ang mga middleware labels, gagana nang maayos ang mga router na iyon. Ang malinis na log ay walang field not found line at walang does not exist line.

Maging tapat sa iyong sarili tungkol sa window na bubukas sa step na ito. Ang isang router na tumutukoy sa isang middleware name na hindi kilala ng v3 (isang typo, o tinanggal na option) ay hindi gagana mula sa sandaling mag-start ang bagong Traefik hanggang sa ma-recreate ang app container nito, na sa isang machine ay tumatagal lamang ng ilang segundo na kailangan ng docker compose up -d para matapos ang listahan. Kung ang isang route ay hindi talaga pwedeng maantala, alisin ang renamed middleware mula sa middlewares label ng router na iyon bago ang pagpapalit at i-add itong muli pagkatapos, at magdesisyon nang maaga kung kaya ng route na mabuhay nang walang IP allow list sa pagitan ng mga sandaling iyon.

Step 5: i-migrate ang mga rules nang paisa-isang service. Gawin ito nang paisa-isang app: i-rewrite ang rule nito sa v3 syntax, i-recreate lamang ang service na iyon gamit ang docker compose up -d app, at i-test ito bago magpatuloy. Kung ang isang service ay may rule na hindi pa kayang i-rewrite, bigyan ang router na iyon ng escape hatch label na traefik.http.routers.app.ruleSyntax=v2 at magpatuloy na.

Step 6: i-off ang compatibility mode. Kapag ang lahat ng rule ay v3 syntax na, burahin ang defaultRuleSyntax at anumang ruleSyntax labels, i-restart ang Traefik, at kumpirmahin na ang bawat router ay green pa rin sa dashboard. Huwag manatili na naka-on ang compatibility mode: deprecated na ang parehong option sa v3.4 at tatanggalin ang mga ito sa susunod na major version, kaya ang mga ito ay tulay lamang, hindi destinasyon.

Bago at pagkatapos: mga label ng isang service

Narito ang isang app na may kasamang maraming pagbabago: isang multi-value Host, isang PathPrefix placeholder, at isang ipWhiteList middleware. Ang 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

At ang parehong service na na-migrate sa 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

Dalawang label ang nagbago. Hinati ng rule ang multi-value Host nito sa dalawang matcher na pinagdugtong ng ||. Pinalitan ang placeholder ng PathRegexp, at ang middleware label ay pinalitan ang ipwhitelist ng ipallowlist. Hindi nagbago ang entrypoint, certificate resolver, router-to-middleware wiring, at service port.

I-test ang bawat service gamit ang dashboard

Pagkatapos ng bawat flip, buksan ang HTTP routers page sa dashboard. Dapat ay kulay green ang lahat ng router. Ang router na may error badge ay nagpapakita ng eksaktong problema nito. Karaniwan itong sanhi ng middleware na hindi na umiiral sa ilalim ng bagong pangalan nito, o isang rule na hindi ma-parse ng v3. Pagkatapos, kumpirmahin ito mula sa labas, isang hostname bawat oras:

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

Ang isang 200 o ang normal na redirect ng iyong app ay nangangahulugang gumagana ang routing at TLS. Ang isang 404 mula sa Traefik ay nangangahulugang hindi nag-up ang router; bumalik sa dashboard at basahin ang error nito. Panatilihing bukas ang docker compose logs -f traefik sa isang pangalawang terminal habang nagtatrabaho, dahil lahat ng parsing failure ay lalabas doon sa sandaling mag-restart ang isang container.

Rollback honesty

Panatilihin ang v2 compose file, ang static configuration nito, at ang acme.json backup hanggang sa ang lahat ng service ay naka-route na sa v3 at nasubukan na nang tama. Ang rollback ay nangangahulugang pag-checkout sa pre-migration commit at pagtakbo ng docker compose up -d. Dapat gamitin ang buong file at hindi lang ang image tag. Ang v3-only labels ay hindi gagana sa v2, katulad ng pagkakamali ng v2 labels sa v3: ang ipallowlist ay hindi umiiral sa v2, at ang isang PathRegexp matcher ay hindi rin gagana doon. Kung ang acme.json ay nawala o nasira, i-restore ang backup copy bago simulan ang v2. Ginagawa ito para hindi maubos ang Let's Encrypt rate limit sa muling pag-issue ng limang certificates nang sabay-sabay.

FAQ

Kailangan ko bang i-rewrite ang lahat ng router rule para sa Traefik v3?

Hindi. Ang simpleng Host(app.example.com) rule na gumagamit ng backticks ay valid sa parehong bersyon, at sapat na ito para sa karamihan ng Compose setups. Kailangan lang mag-rewrite kung ang rule ay gumagamit ng v2-only features: regex o placeholders sa loob ng Path at PathPrefix, maraming hostname sa loob ng isang Host(), quotes sa halip na backticks, o ang mga tinanggal na Headers, HeadersRegexp, at HostHeader matchers.

Ano ang nangyari sa ipWhiteList sa Traefik v3?

Pinangalanan na itong ipAllowList, ngunit hindi nagbago ang configuration sa loob nito, kaya ang v2 label na traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 ay magiging parehong linya na may ipallowlist. Ang mga kasalukuyang v3 release, kasama ang v3.5, ay tinatanggap pa rin ang lumang pangalan bilang isang deprecated alias, kaya patuloy na gagana ang allowlist kahit hindi pa ito pinalitan. Ituring itong pansamantalang solusyon lamang: nakaplano nang tanggalin ang alias na ito, at kapag ang isang middleware name ay hindi na kilala ng Traefik, magkakaroon ito ng router error at 404. Ipapakita ng dashboard ang error, at ang mga request sa hostname na iyon ay magbabalik ng 404.

Kaya pa bang magbasa ng Traefik v3 ng v2 rule syntax?

Oo. I-set ang core.defaultRuleSyntax: v2 sa static configuration para manatiling default ang v2 syntax habang nagmi-migrate, at gamitin ang per-router ruleSyntax=v2 label para sa mga natitirang rules pagkatapos ibalik ang default. Ituring ang parehong opsyon bilang pansamantala: deprecated na ang mga ito sa v3.4 at tatanggalin sa susunod na major version.

Magpapatuloy ba ang aking mga Let's Encrypt certificates pagkatapos ng upgrade?

Oo. Patuloy na binabasa ng Traefik v3 ang acme.json file na isinulat ng v2, kaya hindi muling mag-iissue ng mga certificate dahil lamang nagbago ang binary. Gayunpaman, i-copy ang file sa isang ligtas na lugar bago magsimula, dahil ang rollback o ang pagkabura ng volume na naglalaman ng acme.json ay magpipilit na mag-issue muli ng lahat ng certificate nang sabay-sabay, at ang Let's Encrypt ay nagpapahintulot lamang ng limang duplicate certificates bawat linggo para sa parehong set ng mga hostname.

Bakit hindi mag-start ang Traefik v3 pagkatapos ng upgrade?

Halos palaging dahil ang static configuration ay mayroon pa ring option na tinanggal sa v3, at hindi mag-i-start ang Traefik kung may mga option itong hindi kilala. Para sa mga kilalang leftovers (pilot, providers.docker.swarmMode, experimental.http3), sasabihin ng log ang incompatible deprecated static option found at tutukuyin ang sanhi; para sa anumang hindi pa kilala ng v3, gaya ng tls.caOptional, sasabihin nito ang field not found kasama ang node. Burahin o palitan ang bawat isa, pagkatapos ay i-start muli ang container.