Traefik v2 se v3 migration: kya badlav hain

Traefik v2 और v3 के बीच क्या बदलाव हैं

Traefik v2 से v3 में माइग्रेशन मुख्य रूप से रीनेमिंग (renaming) का काम है। सबसे प्रमुख बदलाव यह है कि ipWhiteList middleware का नाम बदलकर ipAllowList कर दिया गया है। इसके अलावा, v3 में router rule syntax को अधिक सख्त बनाया गया है (PathPrefix अपनी regex विशेषताएँ खो देता है, और कई matchers का नाम बदल दिया गया है या उन्हें हटा दिया गया है)। v3 कुछ providers और options को पूरी तरह से हटा देता है, लेकिन अन्य सभी चीजें जैसे entrypoints, ACME certificate setup, Docker labels workflow, और आपका acme.json पहले की तरह ही काम करते रहेंगे। v3 में एक compatibility mode भी दिया गया है जो v2 rule syntax को काम करने देता है। इससे आप पहले binary को upgrade कर सकते हैं और फिर जोखिम भरे काम के बजाय एक-एक service के rules को धीरे-धीरे लिख सकते हैं।

यह गाइड the Traefik reverse proxy guide में दिए गए label-based Docker Compose setup को मानकर चलती है। वह पेज v3-native है; यह पेज उन systems के लिए है जो अभी भी traefik:v2 tag का उपयोग कर रहे हैं।

Renames aur removals

• HTTP aur TCP middleware dono ke liye ipWhiteList ab ipAllowList hai. Iske andar ke options unchanged hain, isliye sourcerange ka matlab wahi rahega. Current v3 releases (v3.5 samet) purane naam ko deprecated alias ke roop mein accept karte hain aur list ko enforce karte hain, isliye is rename se kuch bhi break nahi hoga. Phir bhi ise rename kar dein: alias ko remove karne ka schedule hai, aur yeh deprecation list se bina kisi warning ke hat jayega.
• providers.docker.swarmMode=true hata diya gaya hai. Swarm ke liye ab apna khud ka provider hai, jise providers.swarm.endpoint ke roop mein configure kiya jata hai.
• pilot section poori tarah se hata diya gaya hai.
• experimental.http3 hata diya gaya hai. HTTP/3 ab seedhe entrypoint par enable hota hai.
• tls.caOptional ko providers aur forwardAuth middleware se hata diya gaya hai.
• InfluxDB v1 metrics provider, Rancher provider, aur Marathon provider hata diye gaye hain.
• Tracing ab OpenTelemetry par move ho gaya hai. Dedicated tracing backends (Jaeger aur Zipkin integrations samet) hata diye gaye hain, aur v3 ab OTLP (OpenTelemetry protocol) export karta hai.
• headers middleware ke andar deprecated ssl* options (sslRedirect, sslHost, aur baaki) hata diye gaye hain. Inki jagah entrypoint redirections aur redirectScheme middleware ne le li hai.

Yeh removals dikhne mein jitne chhote hain, utne hain nahi, kyunki agar static configuration mein koi unknown option milta hai to Traefik start nahi hota. Agar koi purani pilot ya swarmMode line reh jati hai, to container boot ke waqt incompatible deprecated static option found message ke saath ruk jayega jo us option ka naam batayega; agar koi aisa option hai jise Traefik ne kabhi suna hi nahi (jaise typo, ya tls.caOptional), to yeh field not found ke saath rukega. Image tag badalne se pehle static configuration ko clean kar lein.

Agar middleware ka naam aisa hai jise Traefik nahi pehchanta (jaise typo, ya aisa naam jo alias banane ke bajaye remove kar diya gaya ho), to error alag tarah se aata hai: jise router reference karta hai woh route banne ke bajaye error ke saath load hota hai, dashboard use mark karta hai, aur API middleware "offce@docker" does not exist report karta hai. Us hostname par requests 404 receive karengi kyunki router kabhi start hi nahi hua. Dhyan dein ki current v3 mein ipwhitelist is category mein NAHI aata: yeh ek deprecated alias ke roop mein kaam karta hai, isliye bina rename kiya hua label bina kisi dikkat ke kaam karta rahega.

Rule syntax में बदलाव

Rules वह जगह हैं जहाँ वास्तविक rewriting हो सकती है। v3 में ये बदलाव किए गए हैं:

• Matchers के अंदर values के लिए backticks अनिवार्य हैं। v2 में double quotes भी चलते थे; v3 में नहीं, इसलिए Host("app.example.com") को Host(app.example.com) में बदलना होगा।
• PathPrefix अब regular expressions या {id}-style placeholders को नहीं पहचानता है। v2 का PathPrefix(/api/{version:v[0-9]+}) जैसा rule अब Go regular expression syntax में लिखा गया PathRegexp matcher होना चाहिए।
• Matchers अब केवल एक value लेते हैं। v2 में Host(app.example.com,www.example.com) की अनुमति थी; v3 में Host(app.example.com) || Host(www.example.com) का उपयोग करें। इसके अपवाद Header, HeaderRegexp, Query, और QueryRegexp हैं, जो अभी भी एक name और एक value लेते हैं।
• Headers और HeadersRegexp का नाम बदलकर Header और HeaderRegexp कर दिया गया है।
• HostHeader को हटा दिया गया है। Host का उपयोग करें, जो v3 में समान चीज़ को match करता है।
• दो नए matchers जोड़े गए हैं: rule के अंदर client address को match करने के लिए QueryRegexp और ClientIP।

अच्छी खबर: backticks के साथ लिखा गया एक साधारण Host(app.example.com) rule पहले से ही वैध v3 syntax है। अधिकांश छोटे Compose setups में इसी का उपयोग होता है, जिसका अर्थ है कि अधिकांश labels बिना किसी rule edit के migrate हो जाएंगे।

शुरू करने से पहले अपने labels का ऑडिट करें

आप एक ही search से अपने migration के आकार का अनुमान लगा सकते हैं, क्योंकि हर breaking label change एक pattern छोड़ता है जिसे grep ढूंढ सकता है:

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

हर hit का मतलब है एक line जिसे edit करना है। ipwhitelist अब ipallowlist बन जाएगा। HostHeader अब Host बन जाएगा। Headers अब Header बन जाएगा। PathPrefix के अंदर {...} placeholder अब PathRegexp matcher बन जाएगा। Host() के अंदर लगा comma अब || द्वारा जुड़े दो Host() matchers में बदल जाएगा। यदि zero hits मिलते हैं, तो इसका मतलब है कि आपके labels पहले से ही valid v3 syntax में हैं, और migration केवल static configuration और image tag तक ही सीमित रहेगा।

क्या समान रहता है

Entrypoints और उनका HTTP-to-HTTPS redirect, दोनों challenge types के साथ ACME resolvers, exposedByDefault, router और service labels, loadbalancer.server.port, और dashboard, v3 में भी वैसे ही काम करते हैं जैसे v2 में करते थे। आपके certificates भी सुरक्षित रहते हैं, क्योंकि v3 उसी acme.json को पढ़ता है जिसे v2 ने लिखा था। शुरू करने से पहले file का backup जरूर ले लें, क्योंकि यदि rollback के दौरान यह file खो जाती है, तो आप सीधे Let's Encrypt duplicate-certificate rate limit का सामना करेंगे:

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

Migration path

Step 1: वर्तमान configuration को pin करें। किसी भी traefik:latest या traefik:v2 tag को अपने वर्तमान release के अनुसार बदलें, जैसे कि traefik:v2.11, और पूरे compose directory को git में commit करें। इसके बाद का हर step checkout के माध्यम से reversible होगा। यदि docker compose up -d <service> के साथ single service को recreate करना अभी आपको कठिन लगता है, तो the Docker Compose basics guide में इस migration से संबंधित operations दिए गए हैं।

Step 2: static configuration को clean करें और compatibility mode चालू करें। उन सभी options को हटा दें जिन्हें v3 ने drop कर दिया है (pilot, swarmMode, tls.caOptional, experimental.http3), फिर v3 को default रूप से rules को v2 syntax की तरह treat करने के लिए कहें। traefik.yml में:

core:
  defaultRuleSyntax: v2

या compose command: list में एक flag के रूप में: --core.defaultRuleSyntax=v2। Compatibility mode केवल rule syntax को cover करता है। यह हटाए गए options को वापस नहीं लाता है, और यह middlewares को आपके लिए rename नहीं करता है।

Step 3: middleware renames के लिए तैयारी करें। अपने compose files में पुराने names खोजें: grep -rn ipwhitelist docker-compose*.yml। हर ipwhitelist label को ipallowlist में बदलें, लेकिन अभी बदलाव लागू न करें, क्योंकि नया name v2 में मौजूद नहीं है। ये edits अगले step में होने वाले बदलाव के साथ ही लागू होंगे। (यदि कोई छूट जाता है, तो current v3 अभी भी पुराने name को deprecated alias के रूप में स्वीकार करता है, इसलिए list काम करती रहेगी; इसे रात के 2 बजे ठीक करने के बजाय अगले pass में ठीक करें।)

Step 4: image tag बदलें। Traefik image को current v3 release पर सेट करें, जो लिखते समय traefik:v3.5 है, फिर:

docker compose up -d
docker compose logs -f traefik

चूंकि compatibility mode चालू है, आपके v2 rules मैच होते रहेंगे, और चूंकि up -d ने उन services को भी recreate किया है जिनके middleware labels आपने rename किए थे, इसलिए वे routers सही ढंग से start हो जाएंगे। एक healthy log में field not found line और does not exist line नहीं होनी चाहिए।

इस step से होने वाले downtime के बारे में सावधान रहें। एक router जो ऐसे middleware name को reference करता है जिसे v3 नहीं पहचानता (जैसे typo, या हटाया गया option), वह नए Traefik के start होने से लेकर उसके app container के recreate होने तक down रहेगा। एक single box पर, इसमें docker compose up -d के list process करने के कुछ सेकंड लगेंगे। यदि कोई route बिल्कुल भी down नहीं होना चाहिए, तो flip करने से पहले उस router के middlewares label से renamed middleware को हटा दें और बाद में उसे फिर से जोड़ें। पहले से तय कर लें कि क्या वह route बीच के एक मिनट के लिए अपनी IP allow list के बिना रह सकता है।

Step 5: rules को service by service migrate करें। एक बार में एक app पर काम करें: उसके rule को v3 syntax में rewrite करें, केवल उस service को docker compose up -d app के साथ recreate करें, और आगे बढ़ने से पहले उसे test करें। यदि किसी single service के rule को आप अभी rewrite नहीं कर सकते, तो उस router को traefik.http.routers.app.ruleSyntax=v2 label दें और आगे बढ़ते रहें।

Step 6: compatibility mode बंद करें। जब सभी rules v3 syntax में हों, तो defaultRuleSyntax और किसी भी ruleSyntax label को delete करें, Traefik को restart करें, और confirm करें कि dashboard में हर router अभी भी green दिखा रहा है। Compatibility mode के साथ काम न चलाएं: Traefik ने v3.4 में इन दोनों options को deprecated कर दिया है और अगले major version में इन्हें हटा देगा, इसलिए ये केवल एक bridge हैं, destination नहीं।

पहले और बाद में: एक service के labels

यहाँ एक app है जिसमें सभी प्रमुख बदलाव एक साथ दिए गए हैं: एक multi-value Host, एक PathPrefix placeholder, और एक ipWhiteList middleware. 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

और वही service v3 में migrate करने के बाद:

  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

दो labels बदल गए हैं। Rule ने अपने multi-value Host को || द्वारा जुड़े दो matchers में विभाजित कर दिया है और placeholder को PathRegexp से बदल दिया है, और middleware label ने ipwhitelist को ipallowlist से बदल दिया है। Entrypoint, certificate resolver, router-to-middleware wiring, और service port में कोई बदलाव नहीं हुआ है।

Dashboard के साथ प्रत्येक service का परीक्षण करें

प्रत्येक flip के बाद, dashboard का HTTP routers page खोलें। प्रत्येक router हरा (green) होना चाहिए। यदि किसी router पर error badge है, तो वह उसकी सटीक समस्या बताएगा। यह समस्या आमतौर पर एक ऐसा middleware होती है जो अपने नए नाम से मौजूद नहीं है, या कोई ऐसा rule होता है जिसे v3 parse नहीं कर सकता। इसके बाद, एक बार में एक hostname का बाहरी रूप से परीक्षण करें:

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

यदि 200 या आपके app का सामान्य redirect मिलता है, तो इसका अर्थ है कि routing और TLS दोनों सही ढंग से काम कर रहे हैं। Traefik से 404 मिलने का अर्थ है कि router शुरू नहीं हो पाया; dashboard पर वापस जाएं और उसका error देखें। काम करते समय दूसरे terminal में docker compose logs -f traefik को खुला रखें, क्योंकि जैसे ही कोई container restart होता है, प्रत्येक parsing failure वहां दिखाई देता है।

Rollback honesty

v2 compose file, static configuration, aur acme.json backup ko tab tak sambhaal kar rakhein jab tak har service v3 par route na hone lage aur uska sahi se test na ho jaye. Rollback karne ka matlab hai pre-migration commit ko checkout karna aur docker compose up -d ko chalana. Isme poori file ka upyog karna zaroori hai, sirf image tag ka nahi. v3-only labels, v2 ke saath galat kaam karenge, thik waise hi jaise v2 labels v3 ke saath galat kaam karte the: v2 mein ipallowlist nahi hota, aur wahan PathRegexp matcher bhi parse nahi hoga. Agar is process mein acme.json lost ya damage ho gaya hai, to v2 shuru karne se pehle backup copy restore karein. Isse rollback ke dauran Let's Encrypt rate limit khatam nahi hogi, kyunki ek saath paanch certificates re-issue nahi karne padenge.

FAQ

क्या मुझे Traefik v3 के लिए हर router rule को फिर से लिखना होगा?

नहीं। Backticks के साथ लिखा गया एक साधारण Host(app.example.com) rule दोनों versions में मान्य है, और यह अधिकांश Compose setups के लिए पर्याप्त है। पुन: लेखन (Rewriting) केवल वहीं आवश्यक है जहाँ rule में v2-only features का उपयोग किया गया हो: Path और PathPrefix के अंदर regex या placeholders, एक ही Host() के अंदर कई hostnames, backticks के स्थान पर quotes, या हटाए गए Headers, HeadersRegexp, और HostHeader matchers।

Traefik v3 में ipWhiteList का क्या हुआ?

इसे ipAllowList में बदल दिया गया है। इसके अंदर की configuration समान रहती है, इसलिए traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 जैसा v2 label, ipallowlist के साथ वही line बन जाता है। वर्तमान v3 releases, v3.5 सहित, अभी भी पुराने नाम को deprecated alias के रूप में स्वीकार करते हैं, इसलिए बिना renamed label वाला configuration चुपचाप allowlist लागू करता रहता है। इसे rename न करने के कारण के रूप में नहीं, बल्कि एक अस्थायी समाधान के रूप में देखें: इस alias को हटाया जाना निर्धारित है, और यदि Traefik किसी middleware name को नहीं पहचानता है, तो वह router error और 404 के साथ स्पष्ट रूप से fail हो जाता है। Dashboard error दिखाता है, और उस hostname पर requests 404 return करती हैं।

क्या Traefik v3 अभी भी v2 rule syntax पढ़ सकता है?

हाँ। Migration के दौरान v2 syntax को default रखने के लिए static configuration में core.defaultRuleSyntax: v2 सेट करें, और default को वापस बदलने के बाद व्यक्तिगत stragglers के लिए per-router ruleSyntax=v2 label का उपयोग करें। दोनों को अस्थायी मानें: Traefik ने इन्हें v3.4 में deprecated कर दिया था और अगले major version में इन्हें हटा दिया जाएगा।

क्या मेरे Let's Encrypt certificates upgrade के बाद सुरक्षित रहेंगे?

हाँ। Traefik v3 उसी acme.json file को पढ़ना जारी रखता है जिसे v2 ने लिखा था, इसलिए केवल binary बदलने से certificates दोबारा जारी (re-issue) नहीं होते हैं। प्रक्रिया शुरू करने से पहले file को कहीं सुरक्षित जगह copy कर लें, क्योंकि rollback या deleted volume के कारण acme.json का खो जाना, सभी certificates को एक साथ re-issue करने के लिए मजबूर कर देता है, और Let's Encrypt एक ही hostnames के set के लिए प्रति सप्ताह केवल पांच duplicate certificates की अनुमति देता है।

upgrade के बाद Traefik v3 start होने में fail क्यों हो जाता है?

लगभग हमेशा इसलिए क्योंकि static configuration में अभी भी एक ऐसा option है जिसे v3 ने हटा दिया है, और Traefik अनजाने options के साथ start होने से मना कर देता है। ज्ञात leftovers (pilot, providers.docker.swarmMode, experimental.http3) के लिए, log incompatible deprecated static option found कहता है और culprit का नाम बताता है; ऐसी किसी भी चीज़ के लिए जिसे v3 ने कभी नहीं सुना, जैसे tls.caOptional, यह node के साथ field not found कहता है। प्रत्येक को delete या replace करें, फिर container को फिर से start करें।