Traefik v2 से v3 माइग्रेशन: क्या चीजें बदलेंगी?

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

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

यह गाइड Traefik reverse proxy गाइड से label-आधारित Docker Compose सेटअप को आधार मानती है। वह पेज v3-native है; यह गाइड उस सर्वर के लिए है जो अभी भी traefik:v2 tag पर चल रहा है।

नाम परिवर्तन और निष्कासन

• ipWhiteList अब ipAllowList हो गया है, HTTP और TCP दोनों middleware के लिए। इसके अंदर के विकल्प अपरिवर्तित हैं, इसलिए sourcerange का अर्थ बिल्कुल वही रहता है। वर्तमान v3 releases, जिसमें v3.5 भी शामिल है, अभी भी पुराने नाम को एक deprecated alias के रूप में स्वीकार करते हैं और सूची को लागू करना जारी रखते हैं, इसलिए यह नाम परिवर्तन किसी भी चीज़ को बंद नहीं करता है। फिर भी इसे rename करें: alias को भविष्य में हटाने के लिए निर्धारित किया गया है, और यह deprecation सूची से चुपचाप गायब हो जाएगा, न कि शोर मचाते हुए।
• providers.docker.swarmMode=true हटा दिया गया है। Swarm को अपना स्वयं का provider मिलता है, जिसे providers.swarm.endpoint के रूप में configure किया जाता है।
• pilot section पूरी तरह से हटा दिया गया है।
• experimental.http3 हटा दिया गया है। HTTP/3 सीधे entrypoint पर enabled होता है।
• tls.caOptional को providers और forwardAuth middleware से हटा दिया गया है। यदि वह middleware a self-hosted Authentik SSO के सामने स्थित है, तो caOptional line को हटाना ही इसके लिए पूरा migration है, क्योंकि forwardAuth address, trusted headers, और उनके पीछे का outpost, v3 पर समान रूप से व्यवहार करते हैं।
• InfluxDB v1 metrics provider, Rancher provider, और Marathon provider हटा दिए गए हैं।
• Tracing को OpenTelemetry पर ले जाया गया है। समर्पित tracing backends, जिनमें Jaeger और Zipkin integrations शामिल हैं, हटा दिए गए हैं, और v3 इसके बजाय OTLP (OpenTelemetry protocol) export करता है।
• headers middleware के अंदर के deprecated ssl* विकल्प (sslRedirect, sslHost, और बाकी) हटा दिए गए हैं। Entrypoint redirections और redirectScheme middleware ने उनकी जगह ले ली है।

ये निष्कासन दिखने से कहीं अधिक महत्वपूर्ण हैं, क्योंकि Traefik तब start होने से मना कर देता है जब उसकी static configuration में ऐसा विकल्प हो जिसे वह नहीं जानता। एक बची हुई pilot या swarmMode line container को boot के समय incompatible deprecated static option found संदेश के साथ रोक देती है जो उस बची हुई चीज़ का नाम बताता है; एक विकल्प जिसके बारे में Traefik ने कभी नहीं सुना (एक typo, या tls.caOptional) उसे इसके बजाय field not found के साथ रोकता है। image tag को छूने से पहले static configuration को साफ करें।

एक middleware नाम जिसे Traefik वास्तव में नहीं जानता (एक typo, या ऐसा नाम जिसे alias करने के बजाय हटा दिया गया है) अलग तरह से विफल होता है: जो router उसे reference करता है, वह route के बजाय error के साथ load होता है, dashboard उसे mark कर देता है, और API middleware "offce@docker" does not exist रिपोर्ट करता है। उस hostname पर आने वाले requests को 404 मिलता है क्योंकि router कभी चालू ही नहीं हुआ। ध्यान दें कि ipwhitelist वर्तमान v3 पर इस श्रेणी में नहीं है: यह एक deprecated alias के रूप में जीवित है, इसलिए एक unrenamed label चुपचाप काम करना जारी रखता है।

नियम सिंटैक्स में बदलाव

नियम (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]+}) को अब Go regular expression सिंटैक्स में लिखे गए 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 हैं, जो अभी भी एक नाम और एक value लेते हैं।
• Headers और HeadersRegexp का नाम बदलकर Header और HeaderRegexp कर दिया गया है।
• HostHeader को हटा दिया गया है। इसके स्थान पर Host का उपयोग करें, जो v3 में समान कार्य करता है।
• दो नए matchers जोड़े गए हैं: QueryRegexp, और नियम के अंदर client address को match करने के लिए ClientIP।

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

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

आप एक ही search के साथ अपने migration के आकार का अनुमान लगा सकते हैं, क्योंकि प्रत्येक breaking label परिवर्तन एक ऐसा 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 बन जाता है। शून्य hits का मतलब है कि आपके labels पहले से ही valid v3 syntax में हैं, और migration केवल static configuration और image tag तक सीमित रह जाता है। hits से भरी screen यह पूछने का भी एक उचित क्षण है कि क्या यह अभी भी इस box के लिए सही proxy है, और Traefik की Nginx और Caddy के साथ तुलना उस rewriting लागत को उन आवश्यकताओं के मुकाबले रखती है जो अन्य दो आपसे प्रति app मांगते हैं।

जो चीजें समान रहती हैं

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

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

माइग्रेशन का मार्ग

Step 1: वर्तमान में चल रहे वर्ज़न को पिन करें। किसी भी traefik:latest या traefik:v2 टैग को उस सटीक रिलीज़ में बदलें जिस पर आप अभी हैं, उदाहरण के लिए traefik:v2.11, और पूरे compose डायरेक्टरी को git में कमिट करें। बाद का हर स्टेप एक checkout के साथ रिवर्सिबल हो जाता है। यदि docker compose up -d <service> के साथ किसी सिंगल सर्विस को फिर से बनाना अभी तक आपकी आदत में नहीं है, तो the Docker Compose basics guide उन ऑपरेशन्स को कवर करता है जिन पर यह माइग्रेशन आधारित है।

Step 2: स्टैटिक कॉन्फ़िगरेशन को साफ़ करें और कम्पैटिबिलिटी मोड चालू करें। v3 द्वारा हटाए गए हर विकल्प (pilot, swarmMode, tls.caOptional, experimental.http3) को हटा दें, फिर v3 को बताएं कि वह डिफ़ॉल्ट रूप से रूल्स को v2 सिंटैक्स के रूप में ट्रीट करे। traefik.yml में:

core:
  defaultRuleSyntax: v2

या compose command: लिस्ट में एक फ्लैग के रूप में: --core.defaultRuleSyntax=v2। कम्पैटिबिलिटी मोड केवल रूल सिंटैक्स को कवर करता है। यह हटाए गए विकल्पों को वापस नहीं लाता है, और यह आपके लिए मिडलवेयर का नाम नहीं बदलता है।

Step 3: मिडलवेयर रीनेम की तैयारी करें। अपनी compose फाइलों में पुराने नामों के लिए सर्च करें: grep -rn ipwhitelist docker-compose*.yml। हर ipwhitelist लेबल को ipallowlist में बदलें, लेकिन अभी बदलाव लागू न करें, क्योंकि नया नाम v2 में मौजूद नहीं है। ये संपादन अगले स्टेप में बदलाव के साथ ही लागू होते हैं। (यदि कोई छूट जाता है, तो वर्तमान v3 अभी भी पुराने नाम को एक डेप्रिकेटेड एलियास के रूप में मानता है, इसलिए लिस्ट लागू रहती है; इसे रात के 2 बजे के बजाय अगले पास में ठीक करें।)

Step 4: इमेज टैग को फ्लिप करें। Traefik इमेज को वर्तमान v3 रिलीज़ पर सेट करें, जो लिखते समय traefik:v3.5 है, फिर:

docker compose up -d
docker compose logs -f traefik

चूंकि कम्पैटिबिलिटी मोड चालू है, आपके v2 रूल्स मैच करते रहते हैं, और चूंकि up -d ने उन सर्विसेज को भी फिर से बनाया है जिनके मिडलवेयर लेबल आपने बदले थे, वे राउटर्स सही तरीके से काम करते हैं। एक हेल्दी लॉग में कोई field not found लाइन और कोई does not exist लाइन नहीं होती है।

इस स्टेप से खुलने वाली विंडो के बारे में खुद के प्रति ईमानदार रहें। एक राउटर जो ऐसे मिडलवेयर नाम को रेफर करता है जिसे v3 वास्तव में नहीं जानता (कोई टाइपो, या हटाया गया विकल्प), वह नए Traefik के शुरू होने से लेकर उसके ऐप कंटेनर के फिर से बनने तक डाउन रहता है, जिसमें एक बॉक्स पर docker compose up -d को लिस्ट के माध्यम से काम करने में कुछ सेकंड लगते हैं। यदि कोई रूट वास्तव में बंद नहीं हो सकता है, तो फ्लिप करने से पहले उस राउटर के middlewares लेबल से रीनेम किए गए मिडलवेयर को हटा दें और बाद में फिर से जोड़ें, और पहले से तय कर लें कि क्या वह रूट बीच के एक मिनट के लिए अपनी IP अलाउ लिस्ट के बिना रह सकता है।

Step 5: सर्विस-दर-सर्विस रूल्स को माइग्रेट करें। एक बार में एक ऐप पर काम करें: इसके रूल को v3 सिंटैक्स में फिर से लिखें, केवल उस सर्विस को docker compose up -d app के साथ फिर से बनाएं, और आगे बढ़ने से पहले इसका परीक्षण करें। यदि किसी सर्विस में ऐसा रूल है जिसे आप अभी फिर से नहीं लिख सकते हैं, तो उस सिंगल राउटर को एस्केप हैच लेबल traefik.http.routers.app.ruleSyntax=v2 दें और आगे बढ़ते रहें।

Step 6: कम्पैटिबिलिटी मोड बंद करें। जब हर रूल v3 सिंटैक्स में हो, तो defaultRuleSyntax और किसी भी ruleSyntax लेबल को हटा दें, Traefik को रीस्टार्ट करें, और पुष्टि करें कि हर राउटर अभी भी डैशबोर्ड में हरा दिखाई दे रहा है। कम्पैटिबिलिटी मोड चालू रखकर निश्चिंत न हों: Traefik ने v3.4 में दोनों विकल्पों को डेप्रिकेट कर दिया है और उन्हें अगले मेजर वर्ज़न में हटा देगा, इसलिए वे एक पुल हैं, मंजिल नहीं।

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

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

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

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

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

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

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

Rollback की विश्वसनीयता

जब तक सभी services v3 पर route न हो जाएं और उनका पूरी तरह परीक्षण न हो जाए, तब तक v2 compose file, उसकी static configuration और acme.json backup को सुरक्षित रखें। Rollback करने का अर्थ है migration से पहले वाले commit को checkout करना और docker compose up -d चलाना। यह पूरी file होनी चाहिए, न कि केवल image tag, क्योंकि v3-only labels v2 में उसी तरह गलत होते हैं जैसे v2 labels v3 में गलत थे: ipallowlist v2 में मौजूद नहीं है और PathRegexp matcher भी वहां parse नहीं होगा। यदि प्रक्रिया के दौरान acme.json खो गया या क्षतिग्रस्त हो गया है, तो v2 शुरू करने से पहले backup copy को restore करें। इससे rollback के दौरान Let's Encrypt rate limit समाप्त नहीं होगी और आपको एक साथ पांच certificates फिर से जारी नहीं करने पड़ेंगे।

FAQ

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

नहीं। backticks के साथ लिखा गया एक साधारण Host(app.example.com) rule दोनों versions में मान्य है, और यह अधिकांश Compose setups के लिए पर्याप्त है। फिर से लिखने की आवश्यकता केवल तब होती है जब 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.5 सहित वर्तमान v3 releases, अभी भी पुराने नाम को एक deprecated alias के रूप में स्वीकार करते हैं, इसलिए बिना rename किया गया label भी चुपचाप allowlist को लागू करता रहता है। इसे rename न करने के बहाने के बजाय एक अस्थायी सुविधा मानें: इस alias को भविष्य में हटा दिया जाएगा, और यदि Traefik किसी middleware नाम को नहीं पहचानता है, तो वह router error और 404 के साथ विफल हो जाएगा। Dashboard पर error दिखाई देगा, और उस hostname पर आने वाली requests 404 return करेंगी।

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

हाँ। migration के दौरान v2 syntax को default बनाए रखने के लिए static configuration में core.defaultRuleSyntax: v2 set करें, और default को वापस बदलने के बाद बचे हुए routers के लिए 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 एक साथ फिर से जारी करने पड़ेंगे, और Let's Encrypt एक ही set of hostnames के लिए प्रति सप्ताह केवल पाँच duplicate certificates की अनुमति देता है।

upgrade के बाद Traefik v3 start होने में विफल क्यों होता है?

लगभग हमेशा इसलिए क्योंकि 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 करें।