Traefik v2 سے v3 میں منتقلی اور اہم تبدیلیاں

Traefik v2 اور v3 میں کیا تبدیلیاں آئی ہیں

Traefik v2 سے v3 میں منتقلی زیادہ تر ناموں کی تبدیلی کا کام ہے۔ سب سے اہم تبدیلی 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 کو اپ گریڈ کر سکتے ہیں اور پھر ایک ہی پرخطر شام میں سب کچھ کرنے کے بجائے ایک وقت میں ایک سروس کے قواعد (rules) دوبارہ لکھ سکتے ہیں۔

یہ گائیڈ the Traefik reverse proxy guide میں بتائے گئے label-based Docker Compose setup کو فرض کرتی ہے۔ وہ صفحہ v3-native ہے؛ یہ صفحہ ان صارفین کے لیے ہے جو اب بھی traefik:v2 ٹیگ استعمال کر رہے ہیں۔

Renames اور removals

• HTTP اور TCP middleware دونوں کے لیے ipWhiteList اب ipAllowList ہے. اس کے اندر موجود options تبدیل نہیں ہوئے، اس لیے sourcerange کا مطلب وہی رہے گا۔ موجودہ v3 releases، بشمول v3.5، پرانے نام کو deprecated alias کے طور پر قبول کرتے ہیں اور لسٹ پر عمل درآمد جاری رکھتے ہیں، اس لیے اس ایک rename سے کوئی چیز متاثر نہیں ہوگی. پھر بھی اسے rename کر دیں: alias کو ختم کرنے کا شیڈول بن چکا ہے، اور یہ deprecation list سے خاموشی سے غائب ہو جائے گا.
• providers.docker.swarmMode=true ختم کر دیا گیا ہے. Swarm کو اب اپنا provider ملے گا، جسے providers.swarm.endpoint کے طور پر configure کیا جائے گا۔
• pilot section مکمل طور پر ختم کر دیا گیا ہے.
• experimental.http3 ختم کر دیا گیا ہے. HTTP/3 اب براہ راست entrypoint پر enable ہے۔
• tls.caOptional کو providers اور forwardAuth middleware سے ختم کر دیا گیا ہے۔
• InfluxDB v1 metrics provider، Rancher provider، اور Marathon provider ختم کر دیے گئے ہیں۔
• Tracing کو OpenTelemetry پر منتقل کر دیا گیا ہے۔ مخصوص tracing backends، جن میں Jaeger اور Zipkin integrations شامل ہیں، ختم کر دیے گئے ہیں، اور v3 اب اس کے بجائے OTLP (OpenTelemetry protocol) export کرتا ہے۔
• headers middleware کے اندر deprecated ssl* options (sslRedirect، sslHost، اور باقی) ختم کر دیے گئے ہیں۔ ان کی جگہ entrypoint redirections اور redirectScheme middleware نے لے لی ہے۔

یہ removals اتنی اہم نہیں لگتیں جتنی کہ یہ حقیقت میں ہیں، کیونکہ اگر static configuration میں کوئی ایسا option ہو جسے Traefik نہیں جانتا، تو Traefik start ہونے سے انکار کر دیتا ہے۔ اگر کوئی pilot یا swarmMode لائن باقی رہ جائے تو container boot کے وقت incompatible deprecated static option found message کے ساتھ رک جائے گا جو اس leftover option کا نام بتائے گا؛ جبکہ اگر کوئی ایسا option ہو جس کے بارے میں Traefik نے کبھی سنا ہی نہ ہو (جیسے typo، یا tls.caOptional) تو وہ field not found کے ساتھ رکے گا۔ image tag تبدیل کرنے سے پہلے static configuration کو صاف کر لیں۔

اگر middleware کا نام ایسا ہو جسے Traefik واقعی نہیں جانتا (جیسے typo، یا ایسا نام جسے alias بنانے کے بجائے ختم کر دیا گیا ہو) تو وہ مختلف طریقے سے fail ہوتا ہے: وہ router جو اسے reference کرتا ہے error کے ساتھ load ہوتا ہے بجائے route کے، dashboard اسے mark کرتا ہے، اور API middleware "offce@docker" does not exist report کرتا ہے۔ اس hostname پر آنے والی requests کو 404 ملتا ہے کیونکہ router کبھی start ہی نہیں ہوا۔ یاد رکھیں کہ موجودہ v3 میں ipwhitelist اس category میں شامل نہیں ہے: یہ ایک deprecated alias کے طور پر موجود ہے، اس لیے بغیر rename کیا ہوا label خاموشی سے کام کرتا رہے گا۔

Rule syntax mein tabdeeli

Rules woh jagah hain jahan asal rewriting ho sakti hai. v3 mein ye tabdeeliyaan hain:

• Matchers ke andar values ke liye backticks zaroori hain. v2 mein double quotes bhi chalte thay; v3 mein nahi, isliye Host("app.example.com") ko Host(app.example.com) mein badalna hoga.
• PathPrefix ab regular expressions ya {id}-style placeholders ko samajh nahi sakta. v2 ka rule jaise PathPrefix(/api/{version:v[0-9]+}) ab Go regular expression syntax mein likha hua PathRegexp matcher hona chahiye.
• Matchers ab sirf ek value lete hain. v2 mein Host(app.example.com,www.example.com) chal sakta tha; v3 mein Host(app.example.com) || Host(www.example.com) istemal hoga. Iske exceptions Header, HeaderRegexp, Query, aur QueryRegexp hain, jo ab bhi ek naam aur ek value lete hain.
• Headers aur HeadersRegexp ka naam badal kar Header aur HeaderRegexp rakh diya gaya hai.
• HostHeader ko khatam kar diya gaya hai. Host istemal karein, jo v3 mein wahi kaam karta hai.
• Do naye matchers shamil kiye gaye hain: rule ke andar client address match karne ke liye QueryRegexp aur ClientIP.

Achi khabar: backticks ke saath likha gaya plain Host(app.example.com) rule pehle se hi valid v3 syntax hai. Zyadatar chote Compose setups isi tarah istemal hote hain, jis ka matlab hai ke zyadatar labels bina kisi rule edit ke migrate ho jayenge.

شروع کرنے سے پہلے اپنے labels کا جائزہ لیں

آپ ایک سرچ کے ذریعے اپنی migration کی پیمائش کر سکتے ہیں، کیونکہ ہر breaking label تبدیلی ایک ایسا پیٹرن چھوڑتی ہے جسے 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 بن جائیں گے۔ اگر کوئی ہٹ (hit) نہ ملے، تو اس کا مطلب ہے کہ آپ کے 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 نے لکھا تھا۔ کام شروع کرنے سے پہلے فائل کا backup ضرور لے لیں، کیونکہ اگر rollback کے دوران یہ فائل ضائع ہو گئی تو آپ براہ راست Let's Encrypt کے duplicate-certificate rate limit کا شکار ہو جائیں گے:

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

The migration path

Step 1: موجودہ ورژن کو پن (pin) کریں۔ تمام traefik:latest یا traefik:v2 ٹیگز کو اپنے موجودہ ورژن کے مطابق تبدیل کریں، مثال کے طور پر traefik:v2.11، اور مکمل compose ڈائریکٹری کو git میں کمٹ (commit) کریں۔ اس طرح بعد کے تمام اقدامات کو checkout کے ذریعے واپس (reverse) کیا جا سکے گا۔ اگر آپ کے لیے docker compose up -d <service> کے ساتھ کسی ایک سروس کو دوبارہ بنانا (recreate) ابھی آسان نہیں ہے، تو 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: میڈل ویئر کے نئے ناموں کی تیاری کریں۔ اپنی compose فائلوں میں پرانے نام تلاش کریں: grep -rn ipwhitelist docker-compose*.yml۔ ہر ipwhitelist لیبل کو ipallowlist میں تبدیل کریں، لیکن ابھی تبدیلی لاگو نہ کریں، کیونکہ v2 میں نیا نام موجود نہیں ہے۔ یہ تبدیلیاں اگلے مرحلے میں فلیپ (flip) کے ساتھ لاگو ہوں گی۔ (اگر کوئی نام رہ جائے، تو موجودہ v3 پرانے نام کو deprecated alias کے طور پر قبول کرتا ہے، اس لیے لسٹ کام کرتی رہے گی؛ اسے رات 2 بجے کے بجائے اگلے مرحلے میں درست کریں۔)

Step 4: image tag تبدیل کریں۔ Traefik امیج کو موجودہ v3 ورژن پر سیٹ کریں، جو کہ لکھتے وقت traefik:v3.5 ہے، پھر:

docker compose up -d
docker compose logs -f traefik

چونکہ compatibility mode آن ہے، اس لیے آپ کے v2 رولز میچ کرتے رہیں گے، اور چونکہ up -d نے ان سروسز کو بھی دوبارہ بنایا ہے جن کے میڈل ویئر لیبلز آپ نے تبدیل کیے تھے، اس لیے وہ راؤٹرز (routers) درست طریقے سے کام کریں گے۔ ایک درست لاگ (log) میں نہ تو field not found لائن ہوگی اور نہ ہی does not exist لائن۔

اس مرحلے کے دوران ہونے والے وقفے (window) کے بارے میں حقیقت پسند رہیں۔ اگر کوئی راؤٹر ایسے میڈل ویئر نام کا حوالہ دیتا ہے جسے v3 نہیں جانتا (جیسے ٹائپو، یا کوئی ختم شدہ آپشن)، تو وہ اس وقت سے کام کرنا چھوڑ دے گا جب نیا Traefik شروع ہوگا، جب تک کہ اس کا ایپ کنٹینر دوبارہ نہ بن جائے۔ ایک مشین پر اس میں صرف چند سیکنڈ لگتے ہیں جو docker compose up -d کو لسٹ مکمل کرنے کے لیے درکار ہیں۔ اگر کوئی روٹ (route) بالکل بھی رکنا نہیں چاہتا، تو فلیپ کرنے سے پہلے اس راؤٹر کے middlewares لیبل سے ری نیم (renamed) میڈل ویئر ہٹا دیں اور بعد میں اسے دوبارہ شامل کریں، اور پہلے سے فیصلہ کر لیں کہ کیا وہ روٹ اس ایک منٹ کے لیے اپنی IP allow list کے بغیر رہ سکتا ہے۔

Step 5: رولز کو ایک ایک کر کے سروس کے حساب سے مائیگریٹ کریں۔ ایک وقت میں ایک ایپ پر کام کریں: اس کے رول کو v3 سینٹیکس میں دوبارہ لکھیں، صرف اس سروس کو docker compose up -d app کے ساتھ دوبارہ بنائیں، اور آگے بڑھنے سے پہلے اسے ٹیسٹ کریں۔ اگر کسی سروس کے رول کو آپ ابھی تبدیل نہیں کر سکتے، تو اس راؤٹر کو traefik.http.routers.app.ruleSyntax=v2 کا لیبل دیں اور آگے بڑھتے رہیں۔

Step 6: compatibility mode آف کریں۔ جب تمام رولز v3 سینٹیکس میں ہوں، تو defaultRuleSyntax اور تمام ruleSyntax لیبلز کو ڈیلیٹ کریں، Traefik کو ری اسٹارٹ کریں، اور تصدیق کریں کہ ہر راؤٹر ڈیش بورڈ میں ابھی بھی گرین (green) نظر آ رہا ہے۔ Compatibility mode پر مت رکیں: Traefik نے v3.4 میں دونوں آپشنز کو deprecated قرار دے دیا ہے اور اگلے major ورژن میں انہیں ختم کر دے گا، اس لیے یہ صرف ایک عارضی راستہ ہے، منزل نہیں۔

پہلے اور بعد میں: ایک سروس کے لیبلز

یہاں ایک ایسی ایپ ہے جس میں تمام مشہور تبدیلیاں ایک ساتھ شامل ہیں: ایک 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

اور اسی سروس کو 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

دو لیبلز تبدیل ہو گئے۔ رول نے اپنے multi-value Host کو دو matchers میں تقسیم کیا جنہیں || کے ذریعے جوڑا گیا تھا، اور placeholder کو PathRegexp سے بدل دیا، جبکہ middleware لیبل نے ipwhitelist کو ipallowlist سے تبدیل کر دیا۔ entrypoint، certificate resolver، router-to-middleware wiring، اور service port میں کوئی تبدیلی نہیں ہوئی۔

ہر سروس کو ڈیش بورڈ کے ذریعے ٹیسٹ کریں

ہر تبدیلی کے بعد، ڈیش بورڈ کا HTTP routers صفحہ کھولیں۔ تمام روٹرز کا رنگ سبز ہونا چاہیے۔ اگر کسی روٹر پر error badge نظر آئے تو وہ اس کی اصل وجہ بتائے گا۔ عام طور پر یہ کسی ایسے middleware کا مسئلہ ہوتا ہے جو نئے نام کے ساتھ موجود نہیں ہے، یا کوئی ایسا rule ہوتا ہے جسے v3 parse نہیں کر سکتا۔ اس کے بعد، ایک وقت میں ایک hostname کے ذریعے باہر سے تصدیق کریں:

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

اگر 200 یا آپ کی ایپ کا معمول کا redirect نظر آئے تو اس کا مطلب ہے کہ routing اور TLS دونوں درست کام کر رہے ہیں۔ Traefik سے 404 آنے کا مطلب ہے کہ روٹر شروع نہیں ہو سکا؛ ڈیش بورڈ پر واپس جائیں اور اس کا error پڑھیں۔ کام کے دوران دوسرے terminal میں docker compose logs -f traefik کو کھلا رکھیں، کیونکہ جیسے ہی کوئی container restart ہوتا ہے، parsing failure کا ریکارڈ وہاں آ جاتا ہے۔

Rollback honesty

v2 compose file، اس کی static configuration، اور acme.json backup کو تب تک محفوظ رکھیں جب تک تمام services v3 پر route نہ ہو جائیں اور ان کا مکمل استعمال نہ ہو جائے۔ Rollback کرنے کا مطلب ہے کہ migration سے پہلے والا commit check out کریں اور docker compose up -d کو run کریں، اور یہ مکمل file ہونی چاہیے، صرف image tag نہیں۔ v3-only labels، v2 کے تحت اسی طرح غلط ہوں گے جس طرح v2 labels، v3 کے تحت غلط تھے۔ v2 میں ipallowlist موجود نہیں ہے، اور وہاں PathRegexp matcher بھی parse نہیں ہوگا۔ اگر اس عمل کے دوران acme.json ضائع یا خراب ہو گیا ہے، تو v2 شروع کرنے سے پہلے backup copy کو restore کریں۔ اس سے rollback کے دوران Let's Encrypt rate limit کے تحت ایک ساتھ 5 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 وہی ہے۔ اس لیے v2 label جیسے کہ traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24، اب ipallowlist کے ساتھ ایک ہی لائن بن جائے گا۔ موجودہ v3 releases، بشمول v3.5، اب بھی پرانے نام کو deprecated alias کے طور پر قبول کرتے ہیں، اس لیے بغیر نام بدلے والا label خاموشی سے allowlist لاگو کرتا رہتا ہے۔ اسے نام نہ بدلنے کی وجہ کے بجائے عارضی حل سمجھیں: اس alias کو ختم کرنے کا پروگرام ہے، اور اگر Traefik کسی middleware نام کو نہیں پہچانتا تو وہ 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 کو واپس تبدیل کرنے کے بعد انفرادی طور پر باقی ماندہ rules کے لیے per-router ruleSyntax=v2 label استعمال کریں۔ ان دونوں کو عارضی سمجھیں: Traefik نے انہیں v3.4 میں deprecated قرار دے دیا ہے اور اگلے major version میں انہیں ختم کر دے گا۔

کیا میرے Let's Encrypt certificates upgrade کے بعد محفوظ رہیں گے؟

جی ہاں۔ Traefik v3 اس acme.json فائل کو پڑھنا جاری رکھتا ہے جو v2 نے لکھی تھی، اس لیے صرف binary تبدیل ہونے سے certificates دوبارہ جاری (re-issue) نہیں ہوتے۔ کام شروع کرنے سے پہلے فائل کو کسی محفوظ جگہ پر کاپی کر لیں، کیونکہ اگر rollback یا volume delete ہونے کی وجہ سے acme.json ضائع ہو گیا، تو تمام certificates ایک ساتھ دوبارہ جاری کرنے پڑیں گے، اور Let's Encrypt ایک ہی hostnames کے سیٹ کے لیے ہفتے میں صرف 5 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 لکھا آئے گا اور مسئلے کی نشاندہی کرے گا؛ ایسی کسی بھی چیز کے لیے جو v3 نے پہلے کبھی نہیں سنی، جیسے کہ tls.caOptional، یہ node کے ساتھ field not found کہے گا۔ ہر ایک کو delete یا replace کریں، پھر container کو دوبارہ start کریں۔