Jinsi ya kuhama kutoka Traefik v2 kwenda v3

Mabadiliko kati ya Traefik v2 na v3

Uhamiaji kutoka Traefik v2 kwenda v3 kimsingi ni kazi ya kubadili majina, na mabadiliko maarufu zaidi ni middleware ya ipWhiteList kubadilishwa kuwa ipAllowList. Zaidi ya hayo, v3 inaimarisha sintaksia ya sheria za router (PathPrefix inapoteza uwezo wake wa regex, matchers kadhaa zimebadilishwa majina au kuondolewa), inaondoa baadhi ya providers na chaguzi moja kwa moja, na inahakikisha kila kitu kingine kinaendelea kufanya kazi: entrypoints, usanidi wa cheti cha ACME, mtiririko wa kazi wa Docker labels, na acme.json yako yote inabaki kama ilivyo. v3 pia inakuja na hali ya utangamano (compatibility mode) inayofanya sintaksia ya sheria za v2 iendelee kufanya kazi, hivyo unaweza kuboresha binary kwanza na kurekebisha sheria kwa kila huduma moja baada ya nyingine badala ya kufanya kila kitu kwa hatari katika jioni moja.

Mwongozo huu unachukulia kuwa unatumia usanidi wa Docker Compose unaotegemea labels kutoka mwongozo wa Traefik reverse proxy. Ukurasa huo ni wa asili wa v3; huu ni kwa ajili ya seva inayotumia tag ya traefik:v2.

Mabadiliko ya majina na uondoaji wa vipengele

• ipWhiteList sasa inaitwa ipAllowList, kwa ajili ya middleware ya HTTP na TCP. Chaguzi zilizomo ndani hazijabadilika, kwa hivyo sourcerange inadumisha maana yake kamili. Matoleo ya sasa ya v3, ikiwemo v3.5, bado yanakubali jina la zamani kama alias iliyopitwa na wakati na yanaendelea kutekeleza orodha hiyo, hivyo mabadiliko haya ya jina hayatasababisha huduma kukatika. Badilisha jina hilo hata hivyo: alias hiyo imepangiwa kuondolewa, na itatoweka kutoka kwenye orodha ya vipengele vilivyopitwa na wakati bila taarifa yoyote.
• providers.docker.swarmMode=true imeondolewa. Swarm sasa ina provider yake yenyewe, iliyosanidiwa kama providers.swarm.endpoint.
• Sehemu ya pilot imeondolewa kabisa.
• experimental.http3 imeondolewa. HTTP/3 huwashwa moja kwa moja kwenye entrypoint.
• tls.caOptional imeondolewa kutoka kwa providers na kutoka kwa middleware ya forwardAuth. Ikiwa middleware hiyo inalinda mfumo wa Authentik SSO uliopo kwenye seva yako, kufuta mstari wa caOptional ndiyo hatua nzima ya uhamiaji, kwa sababu anwani ya forwardAuth, vichwa vya habari (headers) vinavyoaminika, na outpost iliyo nyuma yao yote hufanya kazi vilevile kwenye v3.
• Provider ya metrics ya InfluxDB v1, provider ya Rancher, na provider ya Marathon zimeondolewa.
• Tracing imehamishiwa kwenye OpenTelemetry. Backends maalum za tracing, ikiwemo ushirikiano wa Jaeger na Zipkin, zimeondolewa, na v3 sasa inatumia OTLP (OpenTelemetry protocol) kwa ajili ya kusafirisha data.
• Chaguzi za ssl* zilizopitwa na wakati ndani ya middleware ya headers (sslRedirect, sslHost, na nyinginezo) zimeondolewa. Redirections za entrypoint na middleware ya redirectScheme zimezichukua nafasi hizo.

Uondoaji huu ni muhimu zaidi kuliko unavyoonekana, kwa sababu Traefik inakataa kuanza ikiwa usanidi wake tuli (static configuration) una chaguo ambalo hailitambui. Mstari uliobakia wa pilot au swarmMode husimamisha container wakati wa boot na ujumbe wa incompatible deprecated static option found unaotaja kipengele hicho kilichobaki; chaguo ambalo Traefik halijawahi kulijua (kosa la kuandika, au tls.caOptional) husimamisha container na ujumbe wa field not found badala yake. Safisha usanidi tuli kabla ya kubadilisha image tag.

Jina la middleware ambalo Traefik halilitambui kabisa (kosa la kuandika, au jina lililoondolewa badala ya kupewa alias) hushindwa kufanya kazi kwa njia tofauti: router inayorejelea middleware hiyo hupakia ikiwa na kosa badala ya njia (route), dashboard huiwekea alama, na API inaripoti middleware "offce@docker" does not exist. Maombi yanayoelekezwa kwenye hostname hiyo hupata 404 kwa sababu router haikufanikiwa kuanza. Kumbuka kuwa ipwhitelist HAIPO katika kundi hili kwenye v3 ya sasa: inabaki kama alias iliyopitwa na wakati, kwa hivyo label isiyobadilishwa jina itaendelea kufanya kazi kimya kimya.

Mabadiliko ya sintaksia ya sheria

Sheria ndipo mahali ambapo uandishi upya wa kweli unaweza kufanyika. Mabadiliko katika v3 ni:

• Alama za backticks zinahitajika kuzunguka thamani ndani ya matchers. v2 ilikubali pia alama za double quotes; v3 haikubali, kwa hivyo Host("app.example.com") lazima iwe Host(app.example.com).
• PathPrefix haielewi tena regular expressions au placeholders za mtindo wa {id}. Sheria ya v2 kama PathPrefix(/api/{version:v[0-9]+}) lazima iwe matcher ya PathRegexp iliyoandikwa kwa sintaksia ya regular expression ya Go.
• Matchers sasa huchukua thamani moja pekee. v2 iliruhusu Host(app.example.com,www.example.com); v3 inataka Host(app.example.com) || Host(www.example.com). Isipokuwa ni Header, HeaderRegexp, Query, na QueryRegexp, ambazo bado huchukua jina pamoja na thamani.
• Headers na HeadersRegexp zimebadilishwa majina kuwa Header na HeaderRegexp.
• HostHeader imeondolewa. Tumia Host, ambayo inalingana na kitu kilekile katika v3.
• Matchers mbili ni mpya: QueryRegexp, na ClientIP kwa ajili ya kulinganisha anwani ya mteja ndani ya sheria.

Habari njema: sheria rahisi ya Host(app.example.com) iliyoandikwa kwa backticks tayari ni sintaksia halali ya v3. Usanidi mwingi mdogo wa Compose hutumia hiyo hasa, jambo linalomaanisha kuwa lebo nyingi huhama bila kuhitaji marekebisho yoyote ya sheria.

Kagua lebo zako kabla ya kuanza

Unaweza kupima ukubwa wa uhamiaji wako kwa utafutaji mmoja, kwa sababu kila mabadiliko ya lebo yanayovunja utangamano huacha alama ambayo grep inaweza kuipata:

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

Kila matokeo ni mstari mmoja wa kuhariri. ipwhitelist inakuwa ipallowlist. HostHeader inakuwa Host. Headers inakuwa Header. Kishika nafasi cha {...} ndani ya PathPrefix kinakuwa kilinganishi cha PathRegexp. Koma ndani ya Host() inakuwa vilinganishi viwili vya Host() vilivyounganishwa na ||. Kutopata matokeo yoyote inamaanisha lebo zako tayari zinafuata sintaksia sahihi ya v3, na uhamiaji unakuwa ni usanidi tuli pamoja na tag ya image pekee. Skrini iliyojaa matokeo pia ni wakati mwafaka wa kujiuliza kama hii bado ndiyo proxy sahihi kwa seva yako, na jinsi Traefik inavyolinganishwa na Nginx na Caddy hupima gharama hiyo ya kuandika upya dhidi ya kile ambacho hizo mbili nyingine zinakuhitaji kwa kila programu.

Vitu vinavyobaki vilevile

Entrypoints na redirect yao ya HTTP-to-HTTPS, ACME resolvers zenye aina zote mbili za challenge, exposedByDefault, router na service labels, loadbalancer.server.port, pamoja na dashboard, vyote hufanya kazi katika v3 kama vilivyofanya katika v2. Vyeti vyako (certificates) pia vitahamia, kwa sababu v3 inaendelea kusoma acme.json iliyoandikwa na v2. Hata hivyo, hifadhi nakala (backup) ya faili hilo kabla ya kuanza, kwa sababu kurudi nyuma (rollback) na kupoteza faili hilo kutakuingiza moja kwa moja kwenye kikomo cha rate limit ya Let's Encrypt ya vyeti vinavyofanana:

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

Njia ya uhamiaji

Hatua ya 1: funga toleo unalotumia sasa. Badilisha tag yoyote ya traefik:latest au traefik:v2 iwe toleo kamili unalotumia, kwa mfano traefik:v2.11, na uweke saraka nzima ya compose kwenye git. Kila hatua inayofuata inaweza kutenduliwa kwa kutumia checkout. Ikiwa kuunda upya huduma moja kwa kutumia docker compose up -d <service> bado si jambo la kawaida kwako, mwongozo wa misingi ya Docker Compose unaelezea shughuli ambazo uhamiaji huu unategemea.

Hatua ya 2: safisha usanidi tuli na uwashe hali ya utangamano (compatibility mode). Ondoa kila chaguo ambalo v3 imeliondoa (pilot, swarmMode, tls.caOptional, experimental.http3), kisha iambie v3 ichukulie sheria kama sintaksia ya v2 kwa chaguo-msingi. Katika traefik.yml:

core:
  defaultRuleSyntax: v2

Au kama flag katika orodha ya command: ya compose: --core.defaultRuleSyntax=v2. Hali ya utangamano inashughulikia sintaksia ya sheria pekee. Haileti tena chaguo zilizofutwa, na haikubadilishii majina ya middlewares.

Hatua ya 3: jitayarishe kubadilisha majina ya middleware. Tafuta katika faili zako za compose majina ya zamani: grep -rn ipwhitelist docker-compose*.yml. Hariri kila label ya ipwhitelist iwe ipallowlist, lakini usitumie mabadiliko hayo bado, kwa sababu jina jipya halipo katika v2. Marekebisho haya yanatolewa pamoja na mabadiliko katika hatua inayofuata. (Ikiwa moja itapita bila kubadilishwa, v3 ya sasa bado inatambua jina la zamani kama alias iliyopitwa na wakati, kwa hivyo orodha inaendelea kutekelezwa; irekebishe katika hatua inayofuata badala ya kuifanya saa 8 usiku.)

Hatua ya 4: badilisha tag ya image. Weka image ya Traefik iwe toleo la sasa la v3, traefik:v3.5 wakati wa kuandika mwongozo huu, kisha:

docker compose up -d
docker compose logs -f traefik

Kwa sababu hali ya utangamano imewashwa, sheria zako za v2 zinaendelea kufanya kazi, na kwa sababu up -d pia imeunda upya huduma ambazo ulibadilisha majina ya labels zao za middleware, routers hizo zinaanza bila hitilafu. Logi nzuri haina mstari wa field not found na haina mstari wa does not exist.

Kuwa mkweli kwako mwenyewe kuhusu muda ambao hatua hii inachukua. Router inayorejelea jina la middleware ambalo v3 hailitambui (kwa sababu ya kosa la kuandika, au chaguo lililoondolewa) inakuwa nje ya mtandao kuanzia wakati Traefik mpya inapoanza hadi container ya programu hiyo itakapoundwa upya, jambo ambalo kwenye seva moja huchukua sekunde chache ambazo docker compose up -d inahitaji ili kumaliza orodha. Ikiwa njia (route) haiwezi kukatika hata kidogo, ondoa middleware iliyobadilishwa jina kutoka kwa label ya middlewares ya router hiyo kabla ya kufanya mabadiliko na uiongeze tena baadaye, na uamue mapema ikiwa njia hiyo inaweza kufanya kazi bila orodha ya IP zinazoruhusiwa kwa dakika hiyo ya mpito.

Hatua ya 5: hamisha sheria huduma kwa huduma. Fanya kazi kwa programu moja kwa wakati mmoja: andika upya sheria yake kwa sintaksia ya v3, unda upya huduma hiyo pekee kwa kutumia docker compose up -d app, na uijaribu kabla ya kuendelea. Ikiwa huduma moja ina sheria ambayo huwezi kuiandika upya bado, ipatie router hiyo label ya dharura ya traefik.http.routers.app.ruleSyntax=v2 na uendelee.

Hatua ya 6: zima hali ya utangamano. Wakati kila sheria inatumia sintaksia ya v3, futa defaultRuleSyntax na labels zozote za ruleSyntax, anzisha upya Traefik, na uthibitishe kuwa kila router bado inaonyesha kijani kwenye dashibodi. Usizoelee kuacha hali ya utangamano ikiwa imewashwa: Traefik iliondoa chaguo zote mbili katika v3.4 na itazifuta kabisa katika toleo kuu lijalo, kwa hivyo ni daraja tu, si mwisho wa safari.

Kabla na baada: lebo za huduma moja

Hii hapa ni programu moja inayobeba kila mabadiliko maarufu kwa wakati mmoja: Host yenye thamani nyingi, kishika nafasi cha PathPrefix, na middleware ya ipWhiteList. Kizuizi cha v2:

  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

Na huduma hiyo hiyo iliyohamia 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

Lebo mbili zimebadilika. Kanuni hiyo imegawanya Host yake yenye thamani nyingi katika matchers mbili zilizounganishwa na || na kubadilisha kishika nafasi hicho kwa PathRegexp, na lebo ya middleware imebadilisha ipwhitelist kwa ipallowlist. Entrypoint, certificate resolver, muunganisho wa router-to-middleware, na port ya huduma havijabadilika.

Jaribu kila huduma kwa kutumia dashboard

Baada ya kila mabadiliko, fungua ukurasa wa HTTP routers wa dashboard. Kila router inapaswa kuwa ya kijani. Router yenye alama ya hitilafu huonyesha tatizo lake kamili, ambalo kwa kawaida ni middleware isiyokuwepo kwa jina lake jipya au kanuni ambayo v3 haiwezi kuisoma. Kisha thibitisha kutoka nje, hostname moja baada ya nyingine:

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

200 au redirect ya kawaida ya programu yako inamaanisha kuwa routing na TLS zote zimefanikiwa. 404 kutoka kwa Traefik inamaanisha kuwa router haikuanza; rudi kwenye dashboard na usome hitilafu yake. Weka docker compose logs -f traefik ikiwa wazi kwenye terminal ya pili wakati unafanya kazi, kwa sababu kila hitilafu ya uchanganuzi (parsing failure) huonekana hapo wakati container inapowaka upya.

Uaminifu wa kurudisha nyuma (rollback)

Hifadhi faili ya v2 compose, usanidi wake tuli, na nakala ya acme.json hadi kila huduma itakapoelekeza kwenye v3 na kufanyiwa majaribio ya kweli. Kurudisha nyuma (rollback) kunamaanisha kurejesha commit ya kabla ya uhamiaji na kuendesha docker compose up -d. Hii lazima iwe faili zima, siyo tu image tag, kwa sababu lebo za v3 pekee hazifanyi kazi kwenye v2 kwa njia ile ile ambayo lebo za v2 hazikufanya kazi kwenye v3: ipallowlist haipo kwenye v2, na kilinganishi cha PathRegexp hakitasomeka huko pia. Ikiwa acme.json ilipotea au kuharibika wakati wa mchakato, rejesha nakala ya chelezo kabla ya kuanza v2, ili rollback isitumie kikomo chako cha Let's Encrypt kwa kutoa upya vyeti vitano kwa wakati mmoja.

FAQ

Je, ni lazima niandike upya kila sheria ya router kwa ajili ya Traefik v3?

Hapana. Sheria ya kawaida ya Host(app.example.com) iliyoandikwa kwa alama za backticks inafanya kazi katika matoleo yote mawili, na hiyo inatosha kwa usanidi mwingi wa Compose. Kuandika upya kunahitajika tu pale ambapo sheria ilitumia vipengele vya v2 pekee: regex au placeholders ndani ya Path na PathPrefix, majina mengi ya host ndani ya Host() moja, alama za quotes badala ya backticks, au matchers zilizofutwa za Headers, HeadersRegexp, na HostHeader.

Nini kimetokea kwa ipWhiteList katika Traefik v3?

Ilibadilishwa jina na kuwa ipAllowList, huku usanidi wake ukiwa haujabadilika, kwa hivyo label ya v2 kama traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 inakuwa mstari uleule wenye ipallowlist ndani yake. Matoleo ya sasa ya v3, ikiwemo v3.5, bado yanakubali jina la zamani kama alias iliyopitwa na wakati, kwa hivyo label ambayo haijabadilishwa jina inaendelea kutekeleza allowlist kimyakimya. Ichukulie hiyo kama muda wa ziada badala ya sababu ya kuruka hatua ya kubadilisha jina: alias hiyo imepangiwa kuondolewa, na jina la middleware ambalo Traefik halilitambui husababisha hitilafu kubwa, ikiambatana na kosa la router na 404. Dashboard huonyesha kosa hilo, na maombi kwa hostname hiyo hurudisha 404.

Je, Traefik v3 bado inaweza kusoma syntax ya sheria za v2?

Ndiyo. Weka core.defaultRuleSyntax: v2 katika usanidi wa static ili kuweka syntax ya v2 kama chaguo-msingi wakati unahamia, na tumia label ya ruleSyntax=v2 kwa kila router inayobaki nyuma baada ya kubadilisha chaguo-msingi kurudi kwenye hali ya awali. Ichukulie yote miwili kama ya muda: Traefik iliyapiga marufuku katika v3.4 na itayaondoa katika toleo kuu lijalo.

Je, vyeti vyangu vya Let's Encrypt vitabaki baada ya upgrade?

Ndiyo. Traefik v3 inaendelea kusoma faili la acme.json lililoandikwa na v2, kwa hivyo vyeti havitolewi upya kwa sababu tu binary imebadilika. Nakili faili hilo mahali salama kabla ya kuanza, kwa sababu rollback au volume iliyofutwa inayopoteza acme.json hulazimisha kutoa kila cheti upya kwa wakati mmoja, na Let's Encrypt inaruhusu vyeti vitano tu vinavyofanana kwa wiki kwa seti ileile ya hostname.

Kwa nini Traefik v3 inashindwa kuanza baada ya upgrade?

Karibu kila mara ni kwa sababu usanidi wa static bado una chaguo ambalo v3 imeliondoa, na Traefik inakataa kuanza ikiwa na chaguo ambazo haitambui. Kwa mabaki yanayojulikana (pilot, providers.docker.swarmMode, experimental.http3) logi husema incompatible deprecated static option found na kutaja chanzo; kwa chochote ambacho v3 haijawahi kukisikia, kama vile tls.caOptional, inasema field not found pamoja na node husika. Futa au badilisha kila moja, kisha anza container tena.