Traefik v2 hadi v3 migration: matatizo ya kuanzia

Mabadiliko kati ya Traefik v2 na v3

Uhamisho kutoka Traefik v2 hadi v3 ni kazi kubwa ya kubadilisha majina. Badiliko maarufu ni lile la kubadilisha jina la middleware ya ipWhiteList kuwa ipAllowList. Zaidi ya hapo, v3 inafanya mkazo kwenye sintaksia ya kanuni za router (PathPrefix hupoteza uwezo wake wa regex, matcher kadhaa hubadilishwa jina au huondolewa), huondoa baadhi ya providers na chaguzi moja kwa moja, na huacha vitu vingine vyote vikiendelea kufanya kazi: entrypoints, usanidi wa cheti cha ACME, mtiririko wa lebo za Docker, na acme.json yako vyote huhamishwa. v3 pia inakuja na hali ya uoambatanisho inayoruhusu sintaksia ya kanuni za v2 kuendelea kufanya kazi. Hivyo unaweza kusasisha faili ya binary kwanza na kisha kuandika upya kanuni kwa kila huduma moja baada ya nyingine badala ya kufanya hivyo vyote siku moja kwa hatari.

Mwongozo huu unadhani unatumia usanidi wa Docker Compose unaotegemea lebo kutoka kwa mwongozo wa proxy ya kurejesha ya Traefik. Ukurasa huo unatumia v3 kiasili; ukurasa huu ni kwa ajili ya seva inayoendelea kutumia tag ya traefik:v2.

Mabadiliko ya majina na yaliyotolewa

• ipWhiteList sasa ni ipAllowList, kwa ajili ya middleware ya HTTP na TCP zote mbili. Chaguzi ndani hazijabadilika, hivyo sourcerange linabaki na maana yake halisi. Toleo za sasa za v3, zikiwemo v3.5, bado zinakubali jina la zamani kama jina mbadala lililotolewa nafasi, na bora zinaendelea kutekeleza orodha, hivyo mabadiliko haya ya jina hayavunji chochote wakati wa kubadilisha. Badilisha jina hata hivyo: jina mbadala limeratibiwa kuondolewa, na litatoweka kutoka kwenye orodha ya yaliyotolewa nafasi kimyakimya, sio kwa kelele.
• providers.docker.swarmMode=true limeondolewa. Swarm hupata mtoa huduma wake mwenyewe, umewekwa kama providers.swarm.endpoint.
• Sehemu ya pilot imeondolewa kabisa.
• experimental.http3 limeondolewa. HTTP/3 imewashwa kwenye entrypoint moja kwa moja.
• tls.caOptional limeondolewa kutoka kwa watoa huduma na kutoka kwa middleware ya forwardAuth.
• Mtoa huduma wa metriki za InfluxDB v1, mtoa huduma wa Rancher, na mtoa huduma wa Marathon wameondolewa.
• Kufuatilia kumehamishiwa kwenye OpenTelemetry. Nyuma za kufuatilia zilizotengwa, ikiwemo ujumuishwaji wa Jaeger na Zipkin, zimeondolewa, na v3 inatoa OTLP (itifaki ya OpenTelemetry) badala yake.
• Chaguzi za ssl* zilizotolewa nafasi ndani ya middleware ya headers (sslRedirect, sslHost, na zilizobaki) zimeondolewa. Maelekezo upya ya entrypoint na middleware ya redirectScheme zimezibadilisha.

Uondoaji huu una umuhimu mkubwa kuliko inavyoonekana, kwa sababu Traefik inakataa kuanza wakati usanidi wake tuli una chaguo ambayo haijui. Mstari wa pilot au swarmMode uliosalia husimamisha chombo wakati wa kuanzisha ujumbe wa incompatible deprecated static option found unaotaja kilichobaki; chaguo ambayo Traefik haijawahi kuisikia kabisa (makosa ya kuandika, au tls.caOptional) husimamisha kwa field not found badala yake. Safisha usanidi tuli kabla ya kugusa lebo ya picha.

Jina la middleware ambalo Traefik halilijui kweli (makosa ya kuandika, au jina lililoondolewa badala ya kupewa jina mbadala) hushindwa kwa njia tofauti: router inayolitaja inapakia kwa kosa badala ya njia, dashboard inalitambulisha, na API inaripoti middleware "offce@docker" does not exist. Maombi kwenye jina hilo la mwenyeji hupata 404 kwa sababu router haijawahi kuanzishwa. Kumbuka kwamba ipwhitelist HAIKO katika kundi hili kwenye v3 ya sasa: linaendelea kuwepo kama jina mbadala lililotolewa nafasi, hivyo lebo isiyobadilishwa jina inaendelea kufanya kazi kimyakimya.

Mabadiliko ya sintaksia ya kanuni

Kanuni ndipo ambapo uandikishaji upya wa kweli unaweza kufanyika. Mabadiliko katika v3:

• Alama za backticks zinahitajika kuzunguka thamani ndani ya matchers. v2 pia ilikubali alama za nukuu mbili; v3 haikubali, hivyo Host("app.example.com") lazima ifanyike kuwa Host(app.example.com).
• PathPrefix haielewi tena misemo ya kawaida (regular expressions) au nafasi za kushikilia (placeholders) za mtindo wa {id}. Kanuni ya v2 kama PathPrefix(/api/{version:v[0-9]+}) lazima ifanyike kuwa matcher ya PathRegexp iliyoandikwa kwa sintaksia ya misemo ya kawaida ya Go.
• Matchers sasa huchukua thamani moja tu. v2 iliruhusu Host(app.example.com,www.example.com); v3 inataka Host(app.example.com) || Host(www.example.com). Mipengo ni Header, HeaderRegexp, Query, na QueryRegexp, ambazo bado huchukua jina pamoja na thamani.
• Headers na HeadersRegexp zimebadilishwa jina na kuitwa Header na HeaderRegexp.
• HostHeader imeondolewa. Tumia Host, ambayo inalinganisha kitu kile kile katika v3.
• Matchers mbili ni mpya: QueryRegexp, na ClientIP kwa kulinganisha anwani ya mteja ndani ya kanuni.

Habari njema: kanuni rahisi ya Host(app.example.com) iliyoandikwa kwa kutumia backticks ni sintaksia halali ya v3 tayari. Mipangilio mingi midogo ya Compose hutumia hiyo hasa, ambacho maana yake lebo nyingi huhama bila mabadiliko yoyote ya kanuni.

Kagua lebo zako kabla hujaanza

Unaweza kupima ukubwa wa uhamisho wako kwa utafutaji mmoja, kwa sababu kila mabadiliko ya lebo yanayovunja kabla yanaacha mfano ambao grep inaweza kupata:

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. Nafasi ya kushikilia ya {...} ndani ya PathPrefix inakuwa kiolezi cha PathRegexp. Koma ndani ya Host() inakuwa violezi viwili vya Host() vilivyounganishwa na ||. Matokeo sifuri ina maana lebo zako tayari ni sintaksia halali ya v3, na uhamisho unafupika kuwa usanidi tuli pamoja na lebo ya picha.

Kile kinachobaki kama kilivyo

Vituo vya kuingia na uelekeaji wao wa HTTP-to-HTTPS, vyanzo vya ACME vyenye aina zote mbili za changamoto, exposedByDefault, lebo za router na service, loadbalancer.server.port, na dashboard zote zinafanya kazi katika v3 kama zilivyofanya katika v2. Cheti zako pia zinahamishwa, kwa sababu v3 bado linaendelea kusoma acme.json ambayo v2 iliandika. Hata hivyo, cheleza faili hilo kabla hujaanza, kwa sababu kurejesha mfumo ambalo hukipoteza kinakuingiza moja kwa moja kwenye kikomo cha kiwango cha cheti cha nakala za Let's Encrypt:

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

Njia ya uhamishaji

Hatua ya 1: weka alama kwenye kile unachoendesha leo. Badilisha lebo yoyote ya traefik:latest au traefik:v2 kuwa toleo halishi ulilopo, kwa mfano traefik:v2.11, na hifadhi saraka nzima ya compose kwenye git. Kila hatua inayofuata inakuwa inayoweza kurudishwa kwa kutumia checkout. Ikiwa uundaji upya wa huduma moja kwa kutumia docker compose up -d <service> bado hujawa tabia yako, mwongozo wa msingi wa Docker Compose unashughulikia shughuli ambazo uhamishaji huu unategemea.

Hatua ya 2: safisha usanidi wa tuli na washa hali ya uoanishaji. Ondoa kila chaguo ambacho v3 limeondoa (pilot, swarmMode, tls.caOptional, experimental.http3), kisha mwambie v3 kuzingatia kanuni kama sintaksia ya v2 kwa chaguo-msingi. Katika traefik.yml:

core:
  defaultRuleSyntax: v2

Au kama bendera katika orodha ya compose command:: --core.defaultRuleSyntax=v2. Hali ya uoanishaji inashughulikia sintaksia ya kanuni tu. Haifufui chaguo zilizoondolewa, wala haibadilishi jina la middleware kwa ajili yako.

Hatua ya 3: andaa mabadiliko ya majina ya middleware. Tafuta majina ya zamani katika faili zako za compose: grep -rn ipwhitelist docker-compose*.yml. Hariri kila lebo ya ipwhitelist kuwa ipallowlist, lakini usitumie mabadiliko hayo bado, kwa sababu jina jipya halipo katika v2. Mabadiliko haya yanaletwa pamoja na kubadilisha toleo katika hatua inayofuata. (Ikiwa moja hupita bila kugundulika, v3 ya sasa bado inaheshimu jina la zamani kama jina mbadala lililopitishwa, hivyo orodha inaendelea kutekeleza; ilirekebishe katika marudio inayofuata badala ya saa 2 alfajiri.)

Hatua ya 4: badilisha lebo ya image. Weka image ya Traefik kuwa toleo la sasa la v3, traefik:v3.5 wakati wa kuandika, kisha:

docker compose up -d
docker compose logs -f traefik

Kwa sababu hali ya uoanishaji imewashwa, kanuni zako za v2 zinaendelea kufanana, na kwa sababu up -d pia imeunda upya huduma ambazo lebo zao za middleware zilibadilishwa jina, hivyo router hizo huanza kwa hali safi. Kumbukumbu yenye afya haina mstari wa field not found wala mstari wa does not exist.

Kuwa mweli kuhusu dirisha ambalo hatua hii inafungua. Router inayorejelea jina la middleware ambalo v3 halilijui kwa kweli (makosa ya kuandika, au chaguo lililoondolewa) haifanyi kazi tangu wakati Traefik mpya anapoanza hadi kontena la programu yake liundwe upya, ambalo kwenye kompyuta moja ni sekunde chache ambazo docker compose up -d anahitaji kushughulikia orodha. Ikiwa njia moja kweli haiwezi kukatika kwa muda, ondoa middleware iliyobadilishwa jini kutoka kwenye lebo ya middlewares ya router hiyo kabla ya kubadilisha na uiweke tena baada ya kubadilisha, na uamua mapema kama njia hiyo inaweza kuishi bila orodha yake ya kuruhusu IP kwa dakika ile katikati.

Hatua ya 5: hamisha kanuni kulingana na huduma. Fanya kazi kwenye programu moja kwa wakati: andika upya kanuni yake kuwa sintaksia ya v3, unda upya hiyo huduma tu kwa kutumia docker compose up -d app, na uijaribu kabla ya kuendelea. Ikiwa huduma moja ina kanuni ambayo huwezi kuandika upya bado, peana router hiyo moja lebo ya njia ya kutoroka traefik.http.routers.app.ruleSyntax=v2 na uendelee.

Hatua ya 6: zima hali ya uoanishaji. Wakati kila kanuni inatumia sintaksia ya v3, futa defaultRuleSyntax na lebo zozote za ruleSyntax, anza upya Traefik, na thibitisha kila router bado inaonyesha kijani kwenye dashibodi. Usikae nayo kwa muda mrefu ukiwa umewasha hali ya uoanishaji: Traefik imepitisha nyakati chaguo zote mbili katika v3.4 na kuziondoa katika toleo kuu linalofuata, hivyo ni daraja, sio mwisho.

Kabla na baada: lebo za huduma moja

Hapa kuna programu moja iliyo na kila mabadiliko maarufu kwa wakati mmoja: Host yenye thamani nyingi, nafasi ya kushikilia PathPrefix, na middleware ya ipWhiteList. Fungu la 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 baada ya kuhamishiwa kwenye 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 zilibadilika. Kanuni lilitenganisha Host yake yenye thamani nyingi kuwa matchers wawili waliounganishwa na || na kubadilisha nafasi ya kushikilia na PathRegexp, na lebo ya middleware ilibadilisha ipwhitelist na ipallowlist. Entry point, kutatua cheti, uunganishaji kati ya router na middleware, na port ya huduma hazikuhama.

Jaribu kila huduma kwa kutumia dashibodi

Baada ya kila mabadiliko, fungua ukurasa wa waendeshaji HTTP wa dashibodi. Kila mwendeshaji lazima uwe kijani. Mwendeshaji mwenye alama ya hitilafu hutaja tatizo lake hasa, ambalo kwa kawaida ni katikati ya mchakato ambayo haipo kwa jina lake jipya au kanuni ambayo v3 haiwezi kuchambua. Kisha thibitisha kutoka nje, jina la mwenyeji moja baada ya nyingine:

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

200 au uelekeo wa kawaida wa programu yako unaashiria kuwa uelekezaji na TLS zote mbili zimefanikiwa. 404 kutoka Traefik inaashiria mwendeshaji haukuanza; rudi kwenye dashibodi na usome hitilafu yake. Acha docker compose logs -f traefik wazi kwenye kituo cha pili unapofanya kazi, kwa sababu kila hitilafu ya uchambuzi huonekana hapo mara kontena inapoanza tena.

Ukweli kuhusu kurudi nyuma

Hifadhi faili ya v2 compose, usanidi wake wa kudumu, na hifadhi nakala ya acme.json hadi kila huduma itakapokuwa ikifanya kazi kwenye v3 na kujaribiwa kwa kweli. Kurudi nyuma kunamaanisha kuangalia toleo la kabla ya uhamishaji na kutekeleza docker compose up -d, na lazima iwe faili nzima, sio lebo ya image tu, kwa sababu lebo za v3 pekee hazifanyi kazi chini ya v2 kwa njia ile ile lebo za v2 hazikufanya kazi chini ya v3: ipallowlist haipo katika v2, na kichujio cha PathRegexp hakitachambua hapo pia. Ikiwa acme.json ilipotea au kuharibika kwenye mchakato, rudisha nakala ya hifadhi kabla ya kuanzisha v2, ili kurudi nyuma kusingeitumia kikomo la kiwango cha Let's Encrypt kutoa tena vyeti tano kwa pamoja.

FAQ

Je, ninahitaji kuandika upya kila kanuni ya router kwa Traefik v3?

Hapana. Kanuni rahisi ya Host(app.example.com) iliyoandikwa kwa kutumia alama ya backticks ni sahihi katika tofauti zote mbili, na hii inashughulikia mipangilio mingi ya Compose. Uandikaji upya unahitajika tu pale ambapo kanuni ilitumia vipengele vilivyopo katika v2 tu: regex au nafasi za kubadilisha ndani ya Path na PathPrefix, majina kadhaa ya host ndani ya Host() moja, alama za nukuu badala ya backticks, au matchers Headers, HeadersRegexp, na HostHeader zilizotolewa.

Nini kimefanyika kwa ipWhiteList katika Traefik v3?

Kilipewa jina jipya la ipAllowList, huku usanidi ndani haukubadilika, hivyo lebo ya v2 kama traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 inakuwa mstari huohuo ikiwa na ipallowlist ndani yake. Toleo za sasa za v3, zikiwemo v3.5, bado zinakubali jina la zamani kama jina mbadala lisilotumika tena, hivyo lebo isiyoandikwa upya bado inatekeleza orodha ya kuruhusu kimyakimya. Chungalia hili kama muda wa kupitishwa tu na sio sababu ya kuruka jina jipya: jina mbadala limeratibiwa kuondolewa, na jina la middleware ambalo Traefik halilijui linashindwa kwa sauti badala yake, likisababisha kosa la router na 404. Dashibodi inaonyesha kosa hilo, na maombi kwa jina hilo la host hurejesha 404.

Je, Traefik v3 bado inaweza kusoma sintaksia ya kanuni ya v2?

Ndio. Weka core.defaultRuleSyntax: v2 katika usanidi tuli ili kudumisha sintaksia ya v2 kama chaguo-msingi wakati unahamia, na tumia lebo ya ruleSyntax=v2 kwa kila router baada ya kubadilisha chaguo-msingi tena. Zingatia zote mbili kama za muda: Traefik imeacha kutumia hizo katika v3.4 na itaziondoa katika toleo kuu linalofuata.

Je, cheti changu cha Let's Encrypt kitaendelea kuwepo baada ya uboreshaji?

Ndio. Traefik v3 bado inasoma faili la acme.json ambalo v2 iliandika, hivyo vyeti havitolewi upya kwa sababu tu faili la binary limebadilika. Nakili faili mahali salama kabla ya kuanza kwa njia yoyote, kwa sababu kurudisha nyuma au kufuta volume ambayo hupoteza acme.json inalazimisha kutoa upya kila cheti kwa wakati mmoja, na Let's Encrypt inaruhusu vyeti vitano tu visivyo tofauti kwa wiki kwa seti ile ile ya majina ya host.

Kwa nini Traefik v3 inashindwa kuanza baada ya uboreshaji?

Karibu kila wakati ni kwa sababu usanidi tuli bado una chaguo ambacho v3 limeondoa, na Traefik inakataa kuanza kwa chaguo ambalo halitambui. Kwa mabaki yanayojulikana sana (pilot, providers.docker.swarmMode, experimental.http3) kumbukumbu inasema incompatible deprecated static option found na inataja sababu; kwa chochote ambacho v3 hajawahi kukisikia, kama vile tls.caOptional, inasema field not found pamoja na nodi. Futa au badilisha kila moja, kisha anza tena chombo hicho.