Traefik v2 to v3 migration: काय बदलेल?

Traefik v2 आणि v3 मधील बदल

Traefik v2 कडून v3 कडे स्थलांतर करताना प्रामुख्याने नावांमध्ये बदल करावे लागतात. उदाहरणार्थ, ipWhiteList middleware चे नाव आता ipAllowList झाले आहे. याव्यतिरिक्त, v3 मध्ये router rule syntax अधिक कडक करण्यात आले आहे (PathPrefix मधील regex वैशिष्ट्ये काढून टाकली आहेत आणि काही matchers ची नावे बदलली आहेत किंवा ते काढून टाकले आहेत). काही providers आणि options पूर्णपणे काढून टाकले आहेत, परंतु इतर सर्व गोष्टी जशाच्या तशा कार्यरत आहेत: entrypoints, ACME certificate setup, Docker labels workflow आणि तुमचा acme.json सर्व काही कायम आहे. v3 मध्ये एक compatibility mode देखील आहे जो v2 rule syntax ला सपोर्ट करतो. यामुळे तुम्ही प्रथम binary upgrade करू शकता आणि एकाच वेळी सर्व बदल करण्याऐवजी प्रत्येक service साठी स्वतंत्रपणे rules पुन्हा लिहू शकता.

हा मार्गदर्शक (guide) the Traefik reverse proxy guide मधील label-based Docker Compose setup वर आधारित आहे. ती page v3-native आहे; ही page अजूनही traefik:v2 tag वापरणाऱ्या सिस्टीमसाठी आहे.

Renames आणि removals

• HTTP आणि TCP middleware साठी आता ipWhiteList चे नाव बदलून ipAllowList करण्यात आले आहे. त्यातील options बदललेले नाहीत, त्यामुळे sourcerange चा अर्थ तोच राहील. सध्याच्या v3 releases मध्ये (v3.5 सह) जुने नाव deprecated alias म्हणून स्वीकारले जाते आणि list लागू ठेवली जाते, त्यामुळे या बदलामुळे काहीही बंद होणार नाही. तरीही नाव बदला: कारण alias काढून टाकण्याचे नियोजन आहे आणि ते deprecation list मधून शांतपणे निघून जाईल.
• providers.docker.swarmMode=true काढून टाकण्यात आले आहे. Swarm ला आता स्वतःचा provider मिळाला आहे, जो providers.swarm.endpoint म्हणून configure केला जातो.
• pilot section पूर्णपणे काढून टाकण्यात आले आहे.
• experimental.http3 काढून टाकण्यात आले आहे. HTTP/3 आता थेट entrypoint वर enable केले जाते.
• providers आणि forwardAuth middleware मधून tls.caOptional काढून टाकण्यात आले आहे.
• InfluxDB v1 metrics provider, Rancher provider, आणि Marathon provider काढून टाकण्यात आले आहेत.
• Tracing आता OpenTelemetry कडे हलवण्यात आले आहे. Jaeger आणि Zipkin integrations सह सर्व dedicated tracing backends काढून टाकण्यात आले आहेत; त्याऐवजी v3 आता OTLP (OpenTelemetry protocol) export करते.
• headers middleware मधील deprecated ssl* options (sslRedirect, sslHost आणि इतर) काढून टाकण्यात आले आहेत. त्यांच्या जागी Entrypoint redirections आणि redirectScheme middleware ने घेतली आहेत.

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

Traefik ला माहित नसलेले middleware name (typo किंवा alias न बनवता काढून टाकलेले नाव) वेगळ्या पद्धतीने fail होते: ज्या router मध्ये त्याचा संदर्भ आहे तो error सह load होतो, dashboard त्यावर mark करते आणि API middleware "offce@docker" does not exist report करते. त्या hostname वर येणाऱ्या requests 404 मिळतात कारण router सुरूच होत नाही. लक्षात ठेवा की सध्याच्या v3 मध्ये ipwhitelist या श्रेणीत येत नाही: ते deprecated alias म्हणून अस्तित्वात आहे, त्यामुळे न बदललेले label शांतपणे काम करत राहते.

नियम सिंटॅक्समध्ये बदल

नियम (Rules) मध्ये प्रत्यक्ष पुनर्लेखन (rewriting) होऊ शकते. v3 मधील बदल:

• Matchers मधील व्हॅल्यूजसाठी 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 आता एकच व्हॅल्यू स्वीकारतात. v2 मध्ये Host(app.example.com,www.example.com) वापरता येत असे; v3 मध्ये Host(app.example.com) || Host(www.example.com) आवश्यक आहे. Header, HeaderRegexp, Query, आणि QueryRegexp हे अपवाद आहेत, कारण ते अजूनही नाव आणि व्हॅल्यू स्वीकारतात.
• Headers आणि HeadersRegexp चे नाव बदलून Header आणि HeaderRegexp करण्यात आले आहे.
• HostHeader काढून टाकण्यात आले आहे. Host वापरा, जे v3 मध्ये तीच गोष्ट मॅच करते.
• दोन नवीन matchers: नियमामध्ये क्लायंट ॲड्रेस मॅच करण्यासाठी QueryRegexp आणि ClientIP.

चांगली बातमी: backticks वापरून लिहिलेला साधा Host(app.example.com) नियम आधीच वैध v3 सिंटॅक्स आहे. बहुतेक लहान Compose सेटअपमध्ये अगदी तसेच वापरले जाते, याचा अर्थ बहुतेक लेबल्स कोणत्याही नियम संपादनाशिवाय (rule edits) मायग्रेट होतील.

सुरुवात करण्यापूर्वी तुमच्या labels तपासा

तुम्ही एका search द्वारे तुमच्या migration चा आकार मोजू शकता, कारण प्रत्येक breaking label change मध्ये एक pattern असतो जो grep शोधू शकतो:

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

प्रत्येक hit म्हणजे एडिट करण्यासाठी एक ओळ. ipwhitelist चे ipallowlist होते. HostHeader चे Host होते. Headers चे Header होते. PathPrefix मधील {...} placeholder चे PathRegexp matcher होते. Host() मधील comma चे || ने जोडलेले दोन Host() matchers होतात. जर zero hits आले, तर तुमचे labels आधीच वैध 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 प्रमाणेच आहे. प्रक्रिया सुरू करण्यापूर्वी फाईलचा backup नक्की घ्या, कारण जर rollback करताना ती फाईल गमावली, तर तुम्ही थेट Let's Encrypt च्या duplicate-certificate rate limit मध्ये अडकू शकता:

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

The migration path

Step 1: सध्या तुम्ही वापरत असलेल्या आवृत्तीला पिन करा. traefik:latest किंवा traefik:v2 टॅग बदलून तुम्ही सध्या वापरत असलेल्या अचूक रिलीजवर सेट करा, उदाहरणार्थ traefik:v2.11, आणि संपूर्ण compose डिरेक्टरी git मध्ये commit करा. यामुळे पुढील प्रत्येक पायरी 'checkout' द्वारे रिव्हर्सिबल (reversible) होईल. जर docker compose up -d <service> वापरून एखादी सिंगल सर्विस पुन्हा तयार करणे तुम्हाला अजून जमलेले नसेल, तर the Docker Compose basics guide मध्ये या स्थलांतरासाठी आवश्यक असलेल्या प्रक्रियांची माहिती दिली आहे.

Step 2: स्टॅटिक कॉन्फिगरेशन स्वच्छ करा आणि compatibility mode सुरू करा. v3 मध्ये काढलेले सर्व ऑप्शन्स (pilot, swarmMode, tls.caOptional, experimental.http3) काढून टाका, त्यानंतर v3 ला सर्व नियम (rules) v2 सिंटॅक्सप्रमाणे मानण्यासाठी सूचना द्या. traefik.yml मध्ये:

core:
  defaultRuleSyntax: v2

किंवा compose command: लिस्टमध्ये फ्लॅग म्हणून: --core.defaultRuleSyntax=v2. Compatibility mode फक्त rule syntax साठी लागू होतो. ते काढून टाकलेले ऑप्शन्स परत आणत नाही आणि middlewares ची नावे आपोआप बदलत नाही.

Step 3: middleware नावांच्या बदलांची तयारी करा. तुमच्या compose फाइल्समध्ये जुनी नावे शोधा: grep -rn ipwhitelist docker-compose*.yml. प्रत्येक ipwhitelist लेबल बदलून ipallowlist करा, परंतु हे बदल लगेच लागू करू नका, कारण नवीन नाव v2 मध्ये अस्तित्वात नाही. हे बदल पुढील पायरीतील बदलासोबतच लागू होतील. (जर एखादे नाव सुटले, तरीही सध्याची v3 आवृत्ती जुने नाव 'deprecated alias' म्हणून स्वीकारते, त्यामुळे ही यादी लागू राहते; रात्री उशिरा दुरुस्त करण्याऐवजी पुढच्या वेळी ते ठीक करा.)

Step 4: image tag बदला. Traefik इमेज सध्याच्या v3 रिलीजवर सेट करा, लेखनाच्या वेळी traefik:v3.5, त्यानंतर:

docker compose up -d
docker compose logs -f traefik

compatibility mode सुरू असल्यामुळे तुमचे v2 नियम मॅच होतील, आणि up -d मुळे ज्या सर्विसेसचे middleware लेबल्स तुम्ही बदलली आहेत त्या पुन्हा तयार झाल्या असल्यामुळे, ते routers व्यवस्थित सुरू होतील. योग्य लॉगमध्ये field not found लाईन आणि does not exist लाईन नसावी.

या पायरीमुळे निर्माण होणाऱ्या वेळेच्या मर्यादेबद्दल (window) वास्तववादी राहा. जर एखादा router अशा middleware नावाला संदर्भ देत असेल जे v3 ला माहित नाही (उदा. टायपो किंवा काढलेले ऑप्शन), तर नवीन Traefik सुरू झाल्यापासून ते app container पुन्हा तयार होईपर्यंत तो router बंद राहील. एका मशीनवर, या प्रक्रियेसाठी docker compose up -d ला लागणारे काही सेकंद लागतील. जर एखादा route अजिबात बंद होऊ शकत नसेल, तर बदलापूर्वी त्या router च्या middlewares लेबल मधून renamed middleware काढून टाका आणि बदलानंतर ते पुन्हा जोडा. तसेच, त्या दरम्यान तो route त्याच्या IP allow list शिवाय चालू राहू शकतो का, याचा निर्णय आधीच घ्या.

Step 5: प्रत्येक सर्विससाठी स्वतंत्रपणे नियमांचे स्थलांतर करा. एका वेळी एकाच app वर काम करा: त्याचा rule v3 सिंटॅक्समध्ये पुन्हा लिहा, फक्त त्या सर्विसला docker compose up -d app वापरून पुन्हा तयार करा, आणि पुढे जाण्यापूर्वी त्याची चाचणी घ्या. जर एखाद्या सर्विसचा rule तुम्ही अजून बदलू शकत नसाल, तर त्या सिंगल router ला traefik.http.routers.app.ruleSyntax=v2 हे escape hatch लेबल द्या आणि पुढे जा.

Step 6: compatibility mode बंद करा. जेव्हा सर्व rules v3 सिंटॅक्समध्ये असतील, तेव्हा defaultRuleSyntax आणि सर्व ruleSyntax लेबल्स काढून टाका, Traefik रीस्टार्ट करा, आणि dashboard मध्ये प्रत्येक router अजूनही 'green' दिसत असल्याची खात्री करा. compatibility mode सुरू ठेवून थांबू नका: Traefik ने v3.4 मध्ये हे दोन्ही ऑप्शन्स deprecated केले आहेत आणि पुढील major version मध्ये ते काढून टाकले जातील, त्यामुळे ते फक्त एक तात्पुरता पूल (bridge) आहेत, अंतिम ध्येय नाहीत.

Before and after: one service's 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

आणि v3 मध्ये migrate केलेले तेच service:

  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 मध्ये कोणताही बदल झालेला नाही.

प्रत्येक service dashboard द्वारे तपासा

प्रत्येक flip नंतर, dashboard ची HTTP routers page उघडा. सर्व routers हिरव्या रंगात असावेत. जर एखाद्या router वर error badge असेल, तर तो नेमकी समस्या दर्शवतो. सहसा, नवीन नावाखाली अस्तित्वात नसलेला middleware किंवा v3 ला parse न होणारा rule ही त्याची कारणे असतात. त्यानंतर, प्रत्येक 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

जोपर्यंत सर्व services v3 वर व्यवस्थित चालत नाहीत आणि त्यांची प्रत्यक्ष चाचणी पूर्ण होत नाही, तोपर्यंत v2 compose file, तिची static configuration आणि acme.json backup सुरक्षित ठेवा. Rollback करण्यासाठी migration पूर्वीचा commit checkout करा आणि docker compose up -d रन करा. यामध्ये संपूर्ण file वापरणे आवश्यक आहे, केवळ image tag बदलून चालणार नाही; कारण v3 साठी असलेले labels v2 मध्ये चुकीचे ठरतात. v2 मध्ये ipallowlist अस्तित्वात नाही आणि तिथे PathRegexp matcher देखील parse होणार नाही. जर प्रवासादरम्यान acme.json गहाळ झाले किंवा खराब झाले, तर v2 सुरू करण्यापूर्वी backup copy रिस्टोर करा. यामुळे rollback करताना Let's Encrypt च्या rate limit मुळे एकाच वेळी पाच certificates पुन्हा जारी करण्याची गरज पडणार नाही.

FAQ

Traefik v3 साठी मला प्रत्येक router rule पुन्हा लिहावी लागेल का?

नाही. backticks वापरून लिहिलेला साधा Host(app.example.com) rule दोन्ही आवृत्त्यांमध्ये वैध आहे, आणि बहुतेक Compose सेटअपमध्ये याची गरज पडत नाही. फक्त अशा ठिकाणी पुन्हा लिहिण्याची गरज आहे जिथे rule मध्ये v2-only फीचर्स वापरले गेले आहेत: जसे की 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 सह तोच राहील. सध्याच्या v3 releases मध्ये (v3.5 सह) जुने नाव deprecated alias म्हणून स्वीकारले जाते, त्यामुळे न बदललेला label शांतपणे allowlist लागू ठेवतो. याला तात्पुरता उपाय समजा, नाव बदलणे टाळण्यासाठी नाही: या alias ला काढून टाकण्याचे नियोजन आहे, आणि Traefik ला माहित नसलेला middleware name वापरल्यास router error आणि 404 सह मोठी त्रुटी (loud failure) दर्शवते. dashboard मध्ये त्रुटी दिसते आणि त्या 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 मध्ये त्या काढून टाकल्या जातील.

upgrade नंतर माझे Let's Encrypt certificates सुरक्षित राहतील का?

हो. Traefik v3, v2 ने लिहिलेली acme.json फाईल वाचणे सुरू ठेवते, त्यामुळे फक्त binary बदलल्यामुळे certificates पुन्हा जारी (re-issue) केले जात नाहीत. तरीही, प्रक्रिया सुरू करण्यापूर्वी फाईल सुरक्षित ठिकाणी कॉपी करा, कारण rollback किंवा acme.json गमावणारा deleted volume मुळे सर्व certificates एकाच वेळी पुन्हा जारी करावे लागतील; आणि Let's Encrypt एकाच hostnames च्या संचासाठी आठवड्याकाठी फक्त पाच duplicate certificates ची परवानगी देते.

upgrade नंतर Traefik v3 सुरू होण्यास का अपयशी ठरते?

बहुतेक वेळा static configuration मध्ये v3 ने काढून टाकलेला option असल्यामुळे असे घडते, आणि Traefik न ओळखता पर्यायांसह (options) सुरू होण्यास नकार देते. pilot, providers.docker.swarmMode, experimental.http3 सारख्या well-known leftovers साठी, log मध्ये incompatible deprecated static option found असे येते आणि त्रुटीचे कारण सांगते; tls.caOptional सारख्या v3 ला माहित नसलेल्या कोणत्याही गोष्टीसाठी, ते node सह field not found असे सांगते. प्रत्येक option काढून टाका किंवा बदला, आणि नंतर container पुन्हा सुरू करा.