Traefik v2 سے v3 منتقلی میں کیا ٹوٹتا ہے؟

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 کر سکتے ہیں اور پھر rules کو ایک وقت میں ایک service کے مطابق تبدیل کر سکتے ہیں، بجائے اس کے کہ ایک ہی خطرناک شام میں سب کچھ تبدیل کریں۔

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

نام کی تبدیلیاں اور حذف شدہ اجزا

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

یہ حذف شدہ اجزا بظاہر جتنے اہم لگتے ہیں، اس سے زیادہ اہم ہیں، کیونکہ جب Traefik کی static configuration میں کوئی نامعلوم option موجود ہو تو Traefik start ہونے سے انکار کر دیتا ہے۔ بچی ہوئی pilot یا swarmMode line container کو boot کے وقت incompatible deprecated static option found message کے ساتھ روک دیتی ہے، جس میں بچی ہوئی setting کا نام ہوتا ہے۔ ایسا option جسے Traefik نے کبھی جانا ہی نہ ہو، مثلاً typo یا tls.caOptional، اس کے بجائے field not found کے ساتھ روک دیتا ہے۔ image tag تبدیل کرنے سے پہلے static configuration صاف کریں۔

ایسا middleware name جسے Traefik واقعی نہیں جانتا، مثلاً typo یا وہ نام جو alias بنائے جانے کے بجائے حذف کر دیا گیا ہو، مختلف طرح سے fail ہوتا ہے۔ جس router میں اس کا حوالہ ہو وہ route کے بجائے error کے ساتھ load ہوتا ہے، dashboard اسے نمایاں کرتا ہے، اور API middleware "offce@docker" does not exist رپورٹ کرتی ہے۔ اس hostname کو بھیجی گئی requests کو 404 ملتا ہے، کیونکہ router start ہی نہیں ہوا۔ یاد رکھیں کہ موجودہ v3 میں ipwhitelist اس زمرے میں شامل نہیں ہے۔ یہ deprecated alias کے طور پر برقرار ہے، اس لیے rename نہ کیا گیا label خاموشی سے کام کرتا رہتا ہے۔

قواعد کا syntax تبدیل ہو گیا ہے

Rules میں اصل rewriting کی جاتی ہے۔ v3 میں یہ تبدیلیاں آئی ہیں:

• Matchers کے اندر values کے گرد backticks لازمی ہیں۔ v2 میں double quotes بھی قابلِ قبول تھے؛ v3 میں نہیں ہیں۔ اس لیے Host("app.example.com") کو Host(app.example.com) میں تبدیل کرنا ہوگا۔
• PathPrefix اب regular expressions یا {id} طرز کے 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 شامل ہیں: QueryRegexp، اور rule کے اندر client address سے match کرنے کے لیے ClientIP۔

اچھی خبر یہ ہے کہ backticks کے ساتھ لکھی ہوئی سادہ Host(app.example.com) rule پہلے ہی v3 syntax کے مطابق ہے۔ زیادہ تر چھوٹے Compose setups میں یہی طریقہ استعمال ہوتا ہے، اس لیے زیادہ تر labels میں rules کو تبدیل کرنے کی ضرورت نہیں پڑے گی۔

شروع کرنے سے پہلے اپنے labels کا audit کریں

آپ ایک ہی search سے migration کا حجم معلوم کر سکتے ہیں، کیونکہ ہر breaking label تبدیلی ایسا pattern چھوڑتی ہے جسے grep تلاش کر سکتا ہے:

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

ہر hit ترمیم کرنے والی ایک line ہے۔ ipwhitelist کو ipallowlist میں تبدیل کریں۔ HostHeader کو Host میں تبدیل کریں۔ Headers کو Header میں تبدیل کریں۔ PathPrefix کے اندر موجود {...} placeholder کو PathRegexp matcher میں تبدیل کریں۔ Host() کے اندر comma کو Host() کے دو matchers میں تبدیل کریں اور انہیں || کے ذریعے جوڑیں۔ اگر کوئی hit نہ ملے تو آپ کے labels پہلے ہی درست v3 syntax میں ہیں، اور migration صرف static configuration اور image tag تک محدود رہ جاتی ہے۔ اگر نتائج کی پوری screen hits سے بھر جائے تو یہ جائزہ لینے کا مناسب وقت بھی ہے کہ آیا یہ اب بھی اس server کے لیے درست proxy ہے، اور Traefik کا Nginx اور Caddy سے موازنہ اس rewriting cost کو اس لاگت کے مقابل رکھتا ہے جو باقی دونوں ہر 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 نے لکھا تھا۔ پھر بھی شروع کرنے سے پہلے اس file کا backup بنا لیں، کیونکہ اگر rollback کے دوران یہ file ضائع ہو جائے تو آپ براہ راست Let's Encrypt کی duplicate-certificate rate limit سے ٹکرا جائیں گے:

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

منتقلی کا راستہ

مرحلہ 1: آج چلنے والی configuration کو pin کریں۔ کسی بھی traefik:latest یا traefik:v2 tag کو اپنے موجودہ exact release پر تبدیل کریں، مثلاً traefik:v2.11، اور پوری compose directory کو git میں commit کریں۔ اس کے بعد ہر مرحلہ checkout کے ذریعے واپس کیا جا سکے گا۔ اگر کسی ایک service کو docker compose up -d <service> کے ذریعے دوبارہ بنانا ابھی معمول کی بات نہیں ہے تو Docker Compose basics guide میں ان operations کی وضاحت ہے جن پر یہ منتقلی منحصر ہے۔

مرحلہ 2: static configuration صاف کریں اور compatibility mode فعال کریں۔ v3 میں حذف کیے گئے تمام options (pilot، swarmMode، tls.caOptional، experimental.http3) ہٹا دیں، پھر v3 کو ہدایت دیں کہ rules کو default طور پر v2 syntax سمجھا جائے۔ traefik.yml میں:

core:
  defaultRuleSyntax: v2

یا compose command: list میں flag کے طور پر: --core.defaultRuleSyntax=v2۔ Compatibility mode صرف rule syntax کا احاطہ کرتا ہے۔ یہ حذف کیے گئے options واپس نہیں لاتا اور نہ ہی middlewares کے نام خود تبدیل کرتا ہے۔

مرحلہ 3: middleware کے نام تبدیل کرنے کی تیاری کریں۔ اپنی compose files میں پرانے نام تلاش کریں: grep -rn ipwhitelist docker-compose*.yml۔ ہر ipwhitelist label کو ipallowlist میں تبدیل کریں، لیکن ابھی یہ تبدیلی لاگو نہ کریں، کیونکہ نیا نام v2 میں موجود نہیں ہے۔ یہ edits اگلے مرحلے میں compatibility mode تبدیل کرنے کے ساتھ ہی جاری ہوں گی۔ (اگر کوئی نام رہ جائے تو موجودہ v3 اب بھی پرانے نام کو deprecated alias کے طور پر قبول کرتا ہے، اس لیے list کا نفاذ جاری رہتا ہے؛ اسے رات 2am پر درست کرنے کے بجائے اگلی pass میں درست کریں۔)

مرحلہ 4: image tag تبدیل کریں۔ Traefik image کو موجودہ v3 release، یعنی تحریر کے وقت traefik:v3.5، پر set کریں، پھر:

docker compose up -d
docker compose logs -f traefik

چونکہ compatibility mode فعال ہے، اس لیے آپ کے v2 rules matching جاری رکھیں گے۔ اور چونکہ up -d نے ان services کو بھی دوبارہ بنایا جن کے middleware labels آپ نے تبدیل کیے تھے، اس لیے وہ routers درست حالت میں شروع ہوں گے۔ صحت مند log میں field not found line اور does not exist line موجود نہیں ہونی چاہیے۔

اس مرحلے سے پیدا ہونے والی window کے بارے میں خود سے حقیقت پسند رہیں۔ ایسا router جو کسی ایسے middleware name کا حوالہ دیتا ہے جسے v3 واقعی نہیں پہچانتا، خواہ وجہ typo ہو یا حذف کیا گیا option، نئے Traefik کے شروع ہونے سے اس وقت تک down رہے گا جب تک اس کا app container دوبارہ نہیں بنایا جاتا۔ ایک box پر یہ وہ چند seconds ہیں جو docker compose up -d کو list مکمل کرنے میں درکار ہوتے ہیں۔ اگر کوئی route واقعی ایک لمحے کے لیے بھی بند نہیں ہو سکتا تو flip سے پہلے اس router کے middlewares label سے renamed middleware ہٹا دیں، پھر بعد میں اسے دوبارہ شامل کریں۔ پہلے سے طے کریں کہ درمیان کے اس ایک minute میں یہ route اپنی IP allow list کے بغیر چل سکتا ہے یا نہیں۔

مرحلہ 5: rules کو service بہ service منتقل کریں۔ ایک وقت میں ایک app پر کام کریں: اس کے rule کو v3 syntax میں دوبارہ لکھیں، docker compose up -d app کے ذریعے صرف اسی service کو دوبارہ بنائیں، اور آگے بڑھنے سے پہلے اسے test کریں۔ اگر کسی service کا rule ابھی دوبارہ نہیں لکھا جا سکتا تو اسی router کو escape hatch label traefik.http.routers.app.ruleSyntax=v2 دیں اور کام جاری رکھیں۔

مرحلہ 6: compatibility mode بند کریں۔ جب ہر rule v3 syntax میں ہو جائے تو defaultRuleSyntax اور ruleSyntax labels حذف کریں، Traefik restart کریں، اور تصدیق کریں کہ dashboard میں ہر router اب بھی سبز دکھائی دے رہا ہے۔ Compatibility mode کو مستقل فعال نہ رکھیں: Traefik نے دونوں options کو v3.4 میں deprecated قرار دیا ہے اور اگلے major version میں انہیں حذف کر دے گا، اس لیے یہ منزل نہیں بلکہ عارضی پل ہے۔

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

یہاں ایک ایپ میں تمام معروف تبدیلیاں بیک وقت موجود ہیں: متعدد اقدار والا 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 میں منتقل ہونے کے بعد:

  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 نے متعدد اقدار والے Host کو || سے جوڑے گئے دو matchers میں تقسیم کیا اور placeholder کو PathRegexp سے تبدیل کیا، جبکہ middleware label میں ipwhitelist کو ipallowlist سے تبدیل کیا گیا۔ entrypoint، certificate resolver، router-to-middleware wiring اور service port میں کوئی تبدیلی نہیں ہوئی۔

ہر سروس کو dashboard سے جانچیں

ہر تبدیلی کے بعد dashboard کا HTTP routers صفحہ کھولیں۔ ہر router سبز ہونا چاہیے۔ error badge والا router مسئلے کی درست وجہ بتاتا ہے۔ عموماً وجہ یہ ہوتی ہے کہ middleware اپنے نئے نام کے تحت موجود نہیں ہوتا، یا rule v3 کو parse نہیں کیا جا سکتا۔ اس کے بعد باہر سے ایک وقت میں ایک hostname کی تصدیق کریں:

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

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

Rollback کی حقیقت پسندی

v2 compose file، اس کی static configuration، اور acme.json backup کو اس وقت تک محفوظ رکھیں جب تک ہر service، v3 کے ذریعے route نہ ہونے لگے اور حقیقی ماحول میں اس کی آزمائش نہ ہو جائے۔ 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 بحال کریں، تاکہ rollback کے دوران آپ کی Let's Encrypt rate limit استعمال نہ ہو اور ایک ہی وقت میں پانچ certificates دوبارہ جاری نہ کرنے پڑیں۔

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 اندر سے تبدیل نہیں ہوئی۔ اس لیے v2 label traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 وہی line بن جاتا ہے جس میں ipallowlist شامل ہو۔ موجودہ v3 releases، بشمول v3.5، اب بھی پرانے نام کو deprecated alias کے طور پر قبول کرتی ہیں، اس لیے rename نہ کیا گیا label خاموشی سے allowlist نافذ کرتا رہتا ہے۔ اسے rename مؤخر کرنے کی وجہ نہ سمجھیں: یہ alias آئندہ remove ہونا ہے، اور ایسا middleware name جسے Traefik واقعی نہیں جانتا، اس کے برعکس واضح failure پیدا کرتا ہے، جس میں router error اور 404 شامل ہوتے ہیں۔ Dashboard میں error دکھائی دیتا ہے، اور اس hostname کو بھیجی گئی requests 404 واپس کرتی ہیں۔

کیا 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 میں remove کر دے گا۔

کیا upgrade کے بعد میرے Let's Encrypt certificates برقرار رہیں گے؟

ہاں۔ Traefik v3 اس acme.json file کو پڑھتا رہتا ہے جو v2 نے لکھی تھی، اس لیے صرف binary تبدیل ہونے کی وجہ سے certificates دوبارہ issue نہیں ہوتے۔ اس کے باوجود شروع کرنے سے پہلے file کو محفوظ جگہ پر copy کریں، کیونکہ rollback یا ایسا deleted volume جس سے acme.json ضائع ہو جائے، تمام certificates ایک ساتھ دوبارہ issue کرنے پر مجبور کرتا ہے، جبکہ Let's Encrypt ایک ہی hostname set کے لیے فی ہفتہ زیادہ سے زیادہ پانچ duplicate certificates کی اجازت دیتا ہے۔

Upgrade کے بعد Traefik v3 start کیوں نہیں ہوتا؟

تقریباً ہمیشہ اس لیے کہ static configuration میں اب بھی ایسا option موجود ہوتا ہے جسے v3 نے remove کر دیا ہے، اور Traefik ایسے options پر start ہونے سے انکار کرتا ہے جنہیں وہ recognise نہیں کرتا۔ معروف باقی رہ جانے والے options (pilot، providers.docker.swarmMode، experimental.http3) کے لیے log incompatible deprecated static option found لکھتا ہے اور مسئلے کی وجہ بتاتا ہے؛ v3 کے لیے بالکل نامعلوم option، جیسے tls.caOptional، کے لیے field not found لکھا جاتا ہے اور متعلقہ node بھی دکھایا جاتا ہے۔ ہر option کو delete یا replace کریں، پھر container دوبارہ start کریں۔