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 अब HTTP और TCP दोनों middleware के लिए ipAllowList हो गया है। इसके अंदर के विकल्प अपरिवर्तित हैं, इसलिए sourcerange का अर्थ बिल्कुल वही रहता है। वर्तमान v3 releases, जिसमें v3.7 भी शामिल है, पुराने नाम को deprecated alias के रूप में स्वीकार करते हैं और सूची को लागू करना जारी रखते हैं, साथ ही इसके लिए एक deprecation warning भी लॉग करते हैं। इसलिए, यह नाम परिवर्तन किसी भी चीज़ को बंद नहीं करेगा। फिर भी इसे rename करें: पुराना नाम deprecated है और v2.11 पहले से ही ipAllowList को समझता है, इसलिए upgrade से पहले ही यह बदलाव लागू किया जा सकता है।
• providers.docker.swarmMode=true को हटा दिया गया है। Swarm को अपना स्वयं का provider मिल गया है, जिसे providers.swarm.endpoint के रूप में configure किया जाता है।
• pilot section पूरी तरह से हटा दिया गया है।
• experimental.http3 को हटा दिया गया है। HTTP/3 अब सीधे entrypoint पर enabled होता है।
• tls.caOptional को providers और forwardAuth middleware से हटा दिया गया है। यदि वह middleware एक self-hosted Authentik SSO के सामने है, तो caOptional लाइन को हटाना ही इसके लिए पूरा 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 के static configuration में कोई ऐसा विकल्प हो जिसे हटा दिया गया है या जिसे वह नहीं पहचानता, तो वह start होने से मना कर देता है। कोई भी बचा हुआ pilot, swarmMode, experimental.http3, या provider tls.caOptional लाइन boot के समय container को रोक देता है: Traefik पहले उस बचे हुए विकल्प का नाम बताते हुए एक लाइन लॉग करता है (उदाहरण के लिए, Docker provider tls.CAOptional विकल्प को v3 में हटा दिया गया है), और फिर incompatible deprecated install configuration option found के साथ fail हो जाता है। v3.4 तक के releases में उस अंतिम संदेश को incompatible deprecated static option found के रूप में लिखा जाता है। कोई ऐसा विकल्प जिसके बारे में Traefik ने कभी नहीं सुना है, जैसे कि कोई typo, उसे field not found और node के साथ रोक देता है। image tag को बदलने से पहले static configuration को साफ करें।

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

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

नियम (rules) वह स्थान हैं जहाँ वास्तविक rewriting हो सकती है। v3 में हुए बदलाव इस प्रकार हैं:

• Quoting में कोई बदलाव नहीं है। दोनों संस्करण rule values को backticks या escaped double quotes में स्वीकार करते हैं और single quotes को अस्वीकार करते हैं, इसलिए Host(app.example.com) और escaped-double-quote 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 जोड़े गए हैं: PathRegexp, और QueryRegexp। ClientIP, जो नियम के भीतर client address का मिलान करने के लिए है, v2.11 में पहले से मौजूद था और इसे बिना किसी बदलाव के बरकरार रखा गया है।

अच्छी खबर यह है कि backticks के साथ लिखा गया एक साधारण Host(app.example.com) नियम पहले से ही मान्य v3 सिंटैक्स है। अधिकांश छोटे Compose सेटअप बिल्कुल इसी का उपयोग करते हैं, जिसका अर्थ है कि अधिकांश labels बिना किसी rule edit के 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

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

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

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

core:
  defaultRuleSyntax: v2

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

चरण 3: v2.11 पर रहते हुए ही मिडलवेयर का नाम बदलें। अपनी compose फाइलों में पुराने नामों के लिए सर्च करें: grep -rn ipwhitelist docker-compose*.yml। हर ipwhitelist लेबल को ipallowlist में बदलें और उन सर्विसेज को docker compose up -d के साथ फिर से बनाएं। v2.11 में पहले से ही IPAllowList मिडलवेयर मौजूद है, इसलिए बदले हुए लेबल फ्लिप से पहले काम करते हैं, और IPWhiteList का डेप्रिकेशन वार्निंग आपके v2 लॉग से हट जाता है। v2.11 से पुरानी रिलीज़ नए नाम को नहीं पहचानती हैं, इसलिए यदि आपने चरण 1 में कोई पुरानी v2 पिन की है, तो पहले traefik:v2.11 पर जाएं। (यदि कोई छूट जाता है, तो वर्तमान v3 अभी भी पुराने नाम को एक डेप्रिकेटेड एलियास के रूप में मानता है, इसलिए लिस्ट लागू रहती है; इसे रात के 2 बजे के बजाय अगले पास में ठीक करें।)

चरण 4: इमेज टैग को फ्लिप करें। Traefik इमेज को वर्तमान v3 रिलीज़ पर सेट करें, 11 अक्टूबर 2026 तक traefik:v3.7 (v3.7.14 नवीनतम पैच है), फिर:

docker compose up -d
docker compose logs -f traefik

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

इस चरण द्वारा खुलने वाली विंडो के बारे में ईमानदार रहें। एक राउटर जो ऐसे मिडलवेयर नाम को रेफर करता है जिसे v3 वास्तव में नहीं जानता (कोई टाइपो, या हटाया गया विकल्प), वह नए Traefik के शुरू होने के क्षण से तब तक डाउन रहता है जब तक आप उसके लेबल को ठीक नहीं करते और उसके ऐप कंटेनर को फिर से नहीं बनाते। यदि कोई रूट वास्तव में बंद नहीं हो सकता है, तो फ्लिप करने से पहले उस राउटर के middlewares लेबल से संदिग्ध मिडलवेयर को हटा दें और बाद में उसे फिर से जोड़ें, और पहले से तय कर लें कि क्या वह रूट बीच के उस एक मिनट के लिए उसके बिना रह सकता है।

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

चरण 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 की सत्यनिष्ठा

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

FAQ

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

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

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

इसका नाम बदलकर ipAllowList कर दिया गया है, जिसमें configuration पहले जैसी ही है। इसलिए, traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 जैसा v2 label, ipallowlist के साथ उसी line में बदल जाता है। v2.11 पहले से ही नए नाम को स्वीकार करता है, इसलिए आप upgrade करने से पहले नाम बदल सकते हैं। v3.7 सहित वर्तमान v3 releases, अभी भी पुराने नाम को एक deprecated alias के रूप में स्वीकार करते हैं, इसलिए बिना नाम बदला हुआ label log में केवल एक warning के साथ allowlist को लागू करना जारी रखता है। इसे नाम बदलने में देरी करने के बजाय एक अस्थायी सुविधा मानें: deprecated नाम वे होते हैं जिन्हें कोई release हटा सकती है, और यदि 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 एक ही hostnames के समूह के लिए प्रति सप्ताह केवल पाँच duplicate certificates की अनुमति देता है।

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

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