Traefik v2 sa v3: Ano ang Masisira sa Migration

Mga pagbabago sa pagitan ng Traefik v2 at v3

Ang migration mula Traefik v2 patungong v3 ay karaniwang tungkol sa pagpapalit ng mga pangalan. Ang pinakakilalang pagbabago ay ang pagpapalit ng pangalan ng ipWhiteList middleware bilang ipAllowList. Bukod dito, mas mahigpit ang v3 sa syntax ng router rule. Inalis ng PathPrefix ang mga regex feature nito, at pinalitan o inalis ang ilang matcher. Tahasang inalis din ang ilang provider at option. Gayunman, patuloy na gumagana ang iba pang bahagi: ang entrypoints, ang ACME certificate setup, ang Docker labels workflow, at ang iyong acme.json. May compatibility mode din ang v3 na nagpapanatili sa paggana ng v2 rule syntax. Dahil dito, maaari mo munang i-upgrade ang binary at isa-isang baguhin ang mga rule ng bawat serbisyo sa halip na gawin ang lahat sa isang mapanganib na gabi.

Ipinapalagay ng gabay na ito ang label-based na Docker Compose setup mula sa gabay sa Traefik reverse proxy. v3-native ang page na iyon; ang gabay na ito ay para sa server na gumagamit pa rin ng traefik:v2 tag.

Ang mga pinalitan at inalis

• Ang ipWhiteList ay naging ipAllowList para sa HTTP at TCP middleware. Hindi nagbago ang mga option sa loob nito, kaya nananatiling eksakto ang kahulugan ng sourcerange. Tinatanggap pa rin ng kasalukuyang v3 releases, kasama ang v3.5, ang dating pangalan bilang deprecated alias at patuloy nitong ipinapatupad ang listahan. Dahil dito, walang mawawalang serbisyo sa mismong paglipat. Palitan pa rin ang pangalan: nakatakda nang alisin ang alias, at mawawala ito sa deprecation list nang tahimik, hindi hayagang ipaaalam.
• Wala na ang providers.docker.swarmMode=true. May sarili nang provider ang Swarm, na kino-configure bilang providers.swarm.endpoint.
• Ganap nang wala ang seksyong pilot.
• Wala na ang experimental.http3. Direktang sine-enable ang HTTP/3 sa entrypoint.
• Wala na ang tls.caOptional sa providers at sa forwardAuth middleware. Kung ang middleware na iyon ay nasa harap ng self-hosted Authentik SSO, ang pagtanggal ng linyang caOptional ang buong migration para rito, dahil pareho pa rin sa v3 ang pagkilos ng forwardAuth address, trusted headers, at outpost sa likod ng mga ito.
• Wala na ang InfluxDB v1 metrics provider, Rancher provider, at Marathon provider.
• Inilipat ang tracing sa OpenTelemetry. Wala na ang mga dedicated tracing backend, kabilang ang Jaeger at Zipkin integrations, at OTLP (ang OpenTelemetry protocol) na ang ine-export ng v3.
• Wala na ang deprecated ssl* options sa loob ng headers middleware (sslRedirect, sslHost, at iba pa). Pinalitan na ang mga ito ng entrypoint redirections at redirectScheme middleware.

Mas mahalaga ang mga pag-aalis na ito kaysa sa inaakala, dahil tumatangging magsimula ang Traefik kapag may option sa static configuration na hindi nito nakikilala. Pinahihinto ng natirang linyang pilot o swarmMode ang container sa pag-boot at nagpapakita ng mensaheng incompatible deprecated static option found na tumutukoy sa natirang option. Kapag option naman itong hindi kailanman nakilala ng Traefik, gaya ng typo o tls.caOptional, field not found ang lalabas. Linisin muna ang static configuration bago palitan ang image tag.

Iba ang resulta kapag middleware name na talagang hindi nakikilala ng Traefik ang ginamit, gaya ng typo o pangalang inalis sa halip na ginawang alias. Naglo-load ang router na tumutukoy rito nang may error sa halip na route, minamarkahan ito ng dashboard, at iniuulat ng API ang middleware "offce@docker" does not exist. Nakatatanggap ng 404 ang mga request sa hostname na iyon dahil hindi nagsimula ang router. Tandaan na HINDI kabilang dito ang ipwhitelist sa kasalukuyang v3: nananatili ito bilang deprecated alias, kaya patuloy na tahimik na gumagana ang label na hindi pinalitan ang pangalan.

Nagbabago ang syntax ng rule

Dito nagaganap ang aktuwal na rewriting. Narito ang mga pagbabago sa v3:

• Kinakailangan na ang backtick sa paligid ng mga value sa loob ng matcher. Tinatanggap din ng v2 ang double quotes, pero hindi na ito tinatanggap ng v3. Kaya dapat gawing Host(app.example.com) ang Host("app.example.com").
• Hindi na nakauunawa ng regular expression o mga placeholder na gaya ng {id} ang PathPrefix. Ang v2 rule na gaya ng PathPrefix(/api/{version:v[0-9]+}) ay dapat gawing PathRegexp matcher na gumagamit ng syntax ng Go regular expression.
• Isang value na lang ang tinatanggap ng mga matcher. Pinahihintulutan ng v2 ang Host(app.example.com,www.example.com); sa v3, dapat itong maging Host(app.example.com) || Host(www.example.com). Ang mga exception ay Header, HeaderRegexp, Query, at QueryRegexp, na tumatanggap pa rin ng pangalan at value.
• Ang Headers at HeadersRegexp ay pinalitan ng pangalan na Header at HeaderRegexp.
• Inalis ang HostHeader. Gamitin ang Host, na tumutugma sa parehong bagay sa v3.
• May dalawang bagong matcher: QueryRegexp, at ClientIP para sa pagtutugma ng client address sa loob ng rule.

Magandang balita: Valid na sa v3 ang isang simpleng Host(app.example.com) rule na may backtick. Eksaktong ganitong setup ang ginagamit ng karamihan sa maliliit na Compose setup, kaya karamihan sa mga label ay maaaring i-migrate nang walang pagbabago sa rule.

Suriin ang iyong mga label bago magsimula

Masusukat mo ang lawak ng iyong migration sa isang search, dahil bawat breaking na pagbabago sa label ay nag-iiwan ng pattern na mahahanap ng grep:

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

Bawat resulta ay isang linyang kailangang i-edit. Nagiging ipallowlist ang ipwhitelist. Nagiging Host ang HostHeader. Nagiging Header ang Headers. Ang {...} placeholder sa loob ng PathPrefix ay nagiging PathRegexp matcher. Ang comma sa loob ng Host() ay nagiging dalawang Host() matcher na pinagdurugtong ng ||. Kapag walang resulta, valid na v3 syntax na ang iyong mga label, kaya ang migration ay nalilimitahan sa static configuration at image tag. Kapag puno ng resulta ang screen, magandang pagkakataon din itong itanong kung ito pa rin ang tamang proxy para sa server, at ipinapakita ng kung paano ikinukumpara ang Traefik sa Nginx at Caddy kung paano maihahambing ang gastos sa rewriting sa mga kinakailangan ng dalawa para sa bawat app.

Mga nananatiling pareho

Pareho pa rin sa v3 ang mga entrypoint at ang HTTP-to-HTTPS redirect ng mga ito, ang ACME resolver na may parehong uri ng challenge, exposedByDefault, ang router at mga label ng service, loadbalancer.server.port, at ang dashboard, gaya noong v2. Magagamit pa rin ang mga certificate mo dahil patuloy na binabasa ng v3 ang acme.json na isinulat ng v2. I-back up pa rin ang file bago magsimula, dahil kapag nawala ito sa rollback, agad mong matatamaan ang duplicate-certificate rate limit ng Let's Encrypt:

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

Ang landas ng migration

Hakbang 1: i-pin ang ginagamit mo ngayon. Palitan ang anumang traefik:latest o traefik:v2 tag ng eksaktong release na ginagamit mo, gaya ng traefik:v2.11, at i-commit ang buong compose directory sa git. Magiging reversible ang bawat kasunod na hakbang gamit ang checkout. Kung hindi mo pa gamay ang pag-recreate ng isang service gamit ang docker compose up -d <service>, ipinapaliwanag sa gabay sa mga pangunahing kaalaman ng Docker Compose ang mga operation na kailangan sa migration na ito.

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

core:
  defaultRuleSyntax: v2

O bilang flag sa compose command: list: --core.defaultRuleSyntax=v2. Sinasaklaw ng compatibility mode ang syntax ng rule lamang. Hindi nito ibinabalik ang mga inalis na option at hindi nito awtomatikong pinapalitan ang pangalan ng mga middleware.

Hakbang 3: ihanda ang pagpapalit ng pangalan ng middleware. Hanapin sa compose files ang mga lumang pangalan: grep -rn ipwhitelist docker-compose*.yml. I-edit ang bawat ipwhitelist label at palitan ng ipallowlist, pero huwag munang ilapat ang pagbabago dahil wala pa sa v2 ang bagong pangalan. Isabay ang mga edit na ito sa paglipat sa susunod na hakbang. (Kung may isang hindi mapalitan, kinikilala pa rin ng kasalukuyang v3 ang lumang pangalan bilang deprecated alias, kaya patuloy na naipapatupad ang listahan; ayusin ito sa susunod na pass, hindi nang alas-2 ng umaga.)

Hakbang 4: palitan ang image tag. Itakda ang Traefik image sa kasalukuyang v3 release, traefik:v3.5 sa oras ng pagsulat, pagkatapos ay:

docker compose up -d
docker compose logs -f traefik

Dahil naka-on ang compatibility mode, patuloy na gagana ang pagtutugma ng iyong v2 rule. Dahil ni-recreate rin ng up -d ang mga service na pinalitan mo ng middleware label, malinis na mag-start ang mga router na iyon. Sa isang healthy na log, walang field not found line at walang does not exist line.

Maging malinaw sa iyong sarili tungkol sa window na binubuksan ng hakbang na ito. Kapag may router na tumutukoy sa middleware name na hindi talaga kilala ng v3—dahil sa typo o inalis na option—down ito mula sa pagsisimula ng bagong Traefik hanggang sa ma-recreate ang app container nito. Sa isang server, karaniwang ilang segundo lang ito habang pinoproseso ng docker compose up -d ang listahan. Kung talagang hindi maaaring mawalan ng serbisyo ang isang route, alisin muna ang pinalitang middleware sa middlewares label ng router bago ang paglipat, at idagdag itong muli pagkatapos. Magpasya nang maaga kung maaari munang gumana ang route nang wala ang IP allow list nito sa minutong iyon.

Hakbang 5: i-migrate ang mga rule service kada service. Isa-isahin ang mga app: isulat muli ang rule nito gamit ang v3 syntax, i-recreate lamang ang service na iyon gamit ang docker compose up -d app, at i-test ito bago magpatuloy. Kung may isang service na may rule na hindi mo pa kayang isulat muli, idagdag sa router na iyon ang escape hatch label na traefik.http.routers.app.ruleSyntax=v2 at magpatuloy.

Hakbang 6: i-off ang compatibility mode. Kapag v3 syntax na ang lahat ng rule, burahin ang defaultRuleSyntax at ang anumang ruleSyntax label, i-restart ang Traefik, at tiyaking green pa rin ang bawat router sa dashboard. Huwag manatili sa compatibility mode: dineprecate ng Traefik ang dalawang option sa v3.4 at aalisin ang mga ito sa susunod na major version. Bridge lamang ang mga ito, hindi ang pangmatagalang configuration.

Bago at pagkatapos: mga label ng isang service

Narito ang isang app na sabay-sabay na naglalaman ng lahat ng kilalang pagbabago: isang multi-value na 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 matapos i-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 nitong Host sa dalawang matcher na pinagdugtong ng || at pinalitan ang placeholder ng PathRegexp. Pinalitan din ng middleware label ang ipwhitelist ng ipallowlist. Hindi nagbago ang entrypoint, certificate resolver, router-to-middleware wiring, at service port.

Subukan ang bawat service gamit ang dashboard

Pagkatapos ng bawat pagbabago, buksan ang HTTP routers page ng dashboard. Dapat green ang bawat router. Ipinapakita ng router na may error badge ang eksaktong problema nito. Karaniwan itong middleware na hindi umiiral sa bago nitong pangalan o rule v3 na hindi ma-parse. Pagkatapos, kumpirmahin mula sa labas, tig-isang hostname:

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

Ang 200 o ang karaniwang redirect ng app mo ay nangangahulugang parehong gumagana pa ang routing at TLS. Ang 404 mula sa Traefik ay nangangahulugang hindi nagsimula ang router. Bumalik sa dashboard at basahin ang error nito. Panatilihing bukas ang docker compose logs -f traefik sa pangalawang terminal habang nagtatrabaho ka, dahil doon agad napupunta ang bawat parsing failure kapag nag-restart ang isang container.

Tapat na rollback

Panatilihin ang v2 compose file, ang static configuration nito, at ang acme.json backup hanggang sa ma-route ang lahat ng service sa v3 at masubukan ang mga ito sa aktuwal na paggamit. Ang pag-rollback ay nangangahulugang pag-check out sa commit bago ang migration at pagpapatakbo ng docker compose up -d. Dapat ang buong file ang ibalik, hindi lamang ang image tag, dahil mali sa v2 ang mga label na para sa v3, gaya ng pagiging mali sa v3 ng mga label na para sa v2: hindi umiiral ang ipallowlist sa v2, at hindi rin ma-parse roon ang PathRegexp matcher. Kung nawala o nasira ang acme.json habang isinasagawa ang proseso, i-restore muna ang backup copy bago simulan ang v2. Sa ganitong paraan, hindi mauubos ng rollback ang Let's Encrypt rate limit sa muling pag-isyu ng limang certificate nang sabay-sabay.

FAQ

Kailangan ko bang isulat muli ang bawat router rule para sa Traefik v3?

Hindi. Valid sa parehong version ang simpleng Host(app.example.com) rule na gumagamit ng backticks, at sapat na ito para sa karamihan ng Compose setup. Kailangan lang itong isulat muli kung gumamit ang rule ng mga feature na v2 lang ang sumusuporta: regex o placeholders sa loob ng Path at PathPrefix, maraming hostname sa iisang Host(), quotes sa halip na backticks, o mga tinanggal nang matcher na Headers, HeadersRegexp, at HostHeader.

Ano ang nangyari sa ipWhiteList sa Traefik v3?

Pinalitan ito ng pangalan na ipAllowList, pero hindi binago ang configuration sa loob nito. Kaya ang v2 label na tulad ng traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 ay nagiging kaparehong linya na may ipallowlist. Tinatanggap pa rin ng mga kasalukuyang v3 release, kabilang ang v3.5, ang lumang pangalan bilang deprecated alias. Dahil dito, patuloy na tahimik na ipinapatupad ng hindi pinalitang label ang allowlist. Ituring ito bilang pansamantalang palugit, hindi bilang dahilan para ipagpaliban ang pagpapalit ng pangalan. Nakaiskedyul nang alisin ang alias. Kapag middleware name na hindi talaga kilala ng Traefik ang ginamit, magkakaroon naman ng router error at 404. Ipinapakita ng dashboard ang error, at 404 ang ibinabalik sa mga request sa hostname na iyon.

Mababasa pa rin ba ng Traefik v3 ang v2 rule syntax?

Oo. Itakda ang core.defaultRuleSyntax: v2 sa static configuration upang manatiling default ang v2 syntax habang nagmi-migrate ka. Gamitin ang per-router ruleSyntax=v2 label para sa mga indibidwal na hindi pa naia-update matapos mong ibalik ang default sa v3 syntax. Ituring na pansamantala ang dalawang setting. Na-deprecate ang mga ito ng Traefik sa v3.4 at aalisin sa susunod na major version.

Mananatili ba ang aking 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 ini-issue ang certificates dahil lang nagbago ang binary. Gayunman, kopyahin muna ang file sa ligtas na lokasyon bago magsimula. Kapag nag-rollback o nabura ang volume at nawala ang acme.json, mapipilitan kang muling i-issue ang lahat ng certificate nang sabay-sabay. Pinapayagan lang ng Let's Encrypt ang limang duplicate certificate bawat linggo para sa parehong set ng hostname.

Bakit hindi nagsisimula ang Traefik v3 pagkatapos ng upgrade?

Halos palagi itong nangyayari dahil may option pa rin sa static configuration na inalis ng v3. Hindi nagsisimula ang Traefik kapag may option na hindi nito kinikilala. Para sa mga kilalang natirang option (pilot, providers.docker.swarmMode, experimental.http3), sinasabi ng log ang incompatible deprecated static option found at tinutukoy nito ang sanhi. Para sa anumang option na hindi kailanman nakilala ng v3, gaya ng tls.caOptional, sinasabi nito ang field not found kasama ang node. Burahin o palitan ang bawat isa, pagkatapos ay muling simulan ang container.