Traefik v2 থেকে v3 মাইগ্রেশন গাইড

Traefik v2 এবং v3 এর মধ্যে কী পরিবর্তন হয়েছে

Traefik v2 থেকে v3-এ মাইগ্রেশন করার প্রধান কাজ হলো নাম পরিবর্তন করা। এর মধ্যে সবচেয়ে পরিচিত পরিবর্তন হলো ipWhiteList middleware-এর নাম পরিবর্তন করে ipAllowList করা হয়েছে। এছাড়া, v3-এ router rule syntax আরও কঠোর করা হয়েছে (PathPrefix এর regex ফিচারগুলো বাদ দেওয়া হয়েছে, এবং বেশ কিছু matcher-এর নাম পরিবর্তন বা রিমুভ করা হয়েছে)। কিছু provider এবং option সরাসরি বাদ দেওয়া হয়েছে, তবে বাকি সব ফিচার আগের মতোই কাজ করবে: entrypoints, ACME certificate setup, Docker labels workflow এবং আপনার acme.json সব কিছুই অপরিবর্তিত থাকবে। v3-এ একটি compatibility mode দেওয়া হয়েছে যা v2 rule syntax সাপোর্ট করে। এর ফলে আপনি প্রথমে binary upgrade করতে পারবেন এবং ঝুঁকি এড়াতে এক রাতে সব পরিবর্তন না করে প্রতিটি service-এর জন্য আলাদাভাবে rule গুলো পুনরায় লিখতে পারবেন।

এই গাইডটি the Traefik reverse proxy guide-এর label-based Docker Compose setup অনুসরণ করে তৈরি করা হয়েছে। ওই পেজটি v3-এর জন্য; আর এই গাইডটি এখনও traefik:v2 ট্যাগ ব্যবহার করা সিস্টেমের জন্য।

রিনেম এবং রিমুভাল (Renames and removals)

• HTTP এবং TCP middleware উভয় ক্ষেত্রেই ipWhiteList এখন ipAllowList। এর ভেতরের অপশনগুলো অপরিবর্তিত, তাই sourcerange এর অর্থ একই থাকছে। বর্তমান v3 রিলিজসমূহ, v3.5 সহ, পুরাতন নামটিকে deprecated alias হিসেবে গ্রহণ করে এবং লিস্টটি কার্যকর রাখে; তাই এই রিনেম করার ফলে কোনো সমস্যা হবে না। তবুও রিনেম করে রাখা উচিত: কারণ aliasটি রিমুভ করার পরিকল্পনা করা হয়েছে এবং এটি deprecation list থেকে নিঃশব্দে চলে যাবে।
• providers.docker.swarmMode=true সরিয়ে ফেলা হয়েছে। Swarm এর জন্য এখন নিজস্ব provider আছে, যা providers.swarm.endpoint হিসেবে কনফিগার করা হয়।
• pilot সেকশনটি সম্পূর্ণভাবে সরিয়ে ফেলা হয়েছে।
• experimental.http3 সরিয়ে ফেলা হয়েছে। এখন সরাসরি entrypoint এ HTTP/3 এনাবল করা যায়।
• providers এবং forwardAuth middleware থেকে tls.caOptional সরিয়ে ফেলা হয়েছে।
• InfluxDB v1 metrics provider, Rancher provider, এবং Marathon provider সরিয়ে ফেলা হয়েছে।
• Tracing এখন OpenTelemetry এ চলে গেছে। Jaeger এবং Zipkin সহ ডেডিকেটেড tracing backends গুলো সরিয়ে ফেলা হয়েছে; এর পরিবর্তে v3 এখন OTLP (OpenTelemetry protocol) এক্সপোর্ট করে।
• headers middleware এর ভেতরে থাকা deprecated ssl* অপশনগুলো (sslRedirect, sslHost, এবং অন্যান্য) সরিয়ে ফেলা হয়েছে। এখন এগুলোর পরিবর্তে entrypoint redirections এবং redirectScheme middleware ব্যবহার করা হয়।

এই রিমুভালগুলো যতটা মনে হচ্ছে তার চেয়ে বেশি গুরুত্বপূর্ণ, কারণ static configuration এ কোনো অজানা অপশন থাকলে Traefik স্টার্ট হতে অস্বীকার করে। কোনো অবশিষ্টাংশ pilot বা swarmMode লাইন থাকলে বুট করার সময় container টি incompatible deprecated static option found মেসেজসহ থেমে যাবে যা ওই অবশিষ্টাংশটিকে নির্দেশ করে; আর Traefik এর কাছে সম্পূর্ণ অপরিচিত কোনো অপশন (যেমন টাইপো বা tls.caOptional) থাকলে এটি field not found মেসেজ দিয়ে থামবে। ইমেজ ট্যাগ পরিবর্তনের আগে অবশ্যই static configuration পরিষ্কার করে নিন।

Traefik এর কাছে কোনো middleware এর নাম সম্পূর্ণ অপরিচিত হলে (যেমন টাইপো, অথবা এমন কোনো নাম যা alias হিসেবে না রেখে সরাসরি রিমুভ করা হয়েছে) সেটি ভিন্নভাবে ফেইল করে: ওই middleware কে রেফার করা router টি রুট হিসেবে লোড হওয়ার পরিবর্তে এরর দিয়ে লোড হয়, ড্যাশবোর্ড এটিকে মার্ক করে এবং API middleware "offce@docker" does not exist রিপোর্ট করে। ওই hostname এ করা রিকোয়েস্টগুলো 404 পায় কারণ router টি কখনোই চালু হতে পারে না। মনে রাখবেন, বর্তমান v3 তে ipwhitelist এই ক্যাটাগরির অন্তর্ভুক্ত নয়: এটি একটি deprecated alias হিসেবে টিকে আছে, তাই রিনেম না করা লেবেলগুলো নিরবচ্ছিন্নভাবে কাজ করে যাবে।

The rule syntax changes

Rules are where real rewriting can happen. The changes in v3:

• Backticks are required around values inside matchers. v2 also accepted double quotes; v3 does not, so Host("app.example.com") must become Host(app.example.com).
• PathPrefix no longer understands regular expressions or {id}-style placeholders. A v2 rule such as PathPrefix(/api/{version:v[0-9]+}) must become a PathRegexp matcher written in Go regular expression syntax.
• Matchers now take a single value. v2 allowed Host(app.example.com,www.example.com); v3 wants Host(app.example.com) || Host(www.example.com). The exceptions are Header, HeaderRegexp, Query, and QueryRegexp, which still take a name plus a value.
• Headers and HeadersRegexp are renamed to Header and HeaderRegexp.
• HostHeader is removed. Use Host, which matches the same thing in v3.
• Two matchers are new: QueryRegexp, and ClientIP for matching the client address inside a rule.

The good news: a plain Host(app.example.com) rule written with backticks is already valid v3 syntax. Most small Compose setups use exactly that, which means most labels migrate with zero rule edits.

শুরু করার আগে আপনার label গুলো পরীক্ষা করে নিন

একটি মাত্র search এর মাধ্যমে আপনি আপনার migration এর আকার পরিমাপ করতে পারেন, কারণ প্রতিটি breaking label পরিবর্তন grep দিয়ে খুঁজে পাওয়া যায় এমন একটি pattern তৈরি করে:

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() matcher এ রূপান্তরিত হবে যা || দিয়ে যুক্ত থাকবে। যদি কোনো hit না পাওয়া যায়, তার মানে আপনার label গুলো ইতিমধ্যে valid v3 syntax ব্যবহার করছে, এবং migration এর কাজ শুধুমাত্র static configuration এবং image tag পর্যন্তই সীমাবদ্ধ থাকবে।

যা অপরিবর্তিত থাকে

Entrypoints এবং তাদের HTTP-to-HTTPS redirect, উভয় challenge type সহ ACME resolvers, exposedByDefault, router এবং service labels, loadbalancer.server.port, এবং dashboard—v3-এ এগুলো v2-এর মতোই কাজ করে। আপনার certificates-ও স্থানান্তরিত হবে, কারণ v3 সেই acme.json পড়তে পারে যা v2 লিখেছিল। কাজ শুরু করার আগে ফাইলটি ব্যাকআপ নিয়ে রাখুন, কারণ ফাইলটি হারিয়ে ফেললে 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: স্ট্যাটিক কনফিগারেশন পরিষ্কার করুন এবং compatibility mode চালু করুন। v3 ভার্সনে বাদ পড়া প্রতিটি অপশন (pilot, swarmMode, tls.caOptional, experimental.http3) রিমুভ করুন, তারপর v3-কে ডিফল্টভাবে নিয়মগুলোকে v2 সিনট্যাক্স হিসেবে গণ্য করতে বলুন। traefik.yml ফাইলে:

core:
  defaultRuleSyntax: v2

অথবা compose command: লিস্টে একটি flag হিসেবে: --core.defaultRuleSyntax=v2। Compatibility mode শুধুমাত্র rule syntax এর জন্য কাজ করে। এটি রিমুভ করা অপশনগুলোকে পুনরায় ফিরিয়ে আনে না এবং middleware গুলোর নাম পরিবর্তন করে দেয় না।

Step 3: middleware রিনেম করার প্রস্তুতি নিন। আপনার compose ফাইলগুলোতে পুরনো নামগুলো খুঁজুন: grep -rn ipwhitelist docker-compose*.yml। প্রতিটি ipwhitelist লেবেল পরিবর্তন করে ipallowlist লিখুন, কিন্তু এখনই পরিবর্তনটি প্রয়োগ করবেন না, কারণ v2 ভার্সনে নতুন নামটি নেই। পরবর্তী ধাপে এই পরিবর্তনগুলো একসাথে কার্যকর হবে। (যদি কোনোটি বাদ পড়ে যায়, তবে বর্তমান v3 পুরনো নামটি deprecated alias হিসেবে গ্রহণ করে, তাই লিস্টটি কাজ চালিয়ে যাবে; রাত ২টোর পরিবর্তে পরবর্তী ধাপে এটি ঠিক করে নিন।)

Step 4: image tag পরিবর্তন করুন। Traefik image-টি বর্তমান v3 রিলিজ, যা লেখার সময় ছিল traefik:v3.5, সেটি সেট করুন, তারপর:

docker compose up -d
docker compose logs -f traefik

যেহেতু compatibility mode চালু আছে, তাই আপনার v2 নিয়মগুলো কাজ করবে, এবং যেহেতু up -d সেই সার্ভিসগুলোকেও পুনরায় তৈরি করেছে যেগুলোর middleware লেবেল আপনি রিনেম করেছেন, তাই সেই রাউটারগুলো সঠিকভাবে চালু হবে। একটি সুস্থ log-এ কোনো field not found লাইন বা does not exist লাইন থাকবে না।

এই ধাপটি যে সময়সীমা তৈরি করবে সে সম্পর্কে সচেতন থাকুন। একটি রাউটার যদি এমন কোনো middleware নাম রেফার করে যা v3 জানে না (যেমন টাইপো বা রিমুভ করা অপশন), তবে নতুন Traefik চালু হওয়ার মুহূর্ত থেকে অ্যাপ কন্টেইনারটি পুনরায় তৈরি না হওয়া পর্যন্ত সেটি অচল থাকবে। একটি সিঙ্গেল সার্ভারে docker compose up -d এর লিস্ট প্রসেস করতে মাত্র কয়েক সেকেন্ড সময় লাগে। যদি কোনো রুট একেবারেই বন্ধ হওয়া কাম্য না হয়, তবে পরিবর্তনের আগে সেই রাউটারের middlewares লেবেল থেকে রিনেম করা middleware টি সরিয়ে ফেলুন এবং পরে পুনরায় যোগ করুন। সেই সময়ের জন্য রুটটি তার IP allow list ছাড়া চলতে পারবে কি না তা আগে থেকেই ঠিক করে রাখুন।

Step 5: প্রতিটি সার্ভিস অনুযায়ী নিয়মগুলো মাইগ্রেট করুন। প্রতিটি অ্যাপ নিয়ে একে একে কাজ করুন: এর rule-টি v3 সিনট্যাক্সে লিখুন, শুধুমাত্র সেই সার্ভিসটিকে docker compose up -d app দিয়ে পুনরায় তৈরি করুন, এবং পরবর্তী ধাপে যাওয়ার আগে এটি টেস্ট করুন। যদি কোনো সার্ভিসের rule আপনি এখনো পরিবর্তন করতে না পারেন, তবে সেই রাউটারটির জন্য traefik.http.routers.app.ruleSyntax=v2 লেবেলটি ব্যবহার করুন এবং কাজ চালিয়ে যান।

Step 6: compatibility mode বন্ধ করুন। যখন প্রতিটি rule v3 সিনট্যাক্সে চলে আসবে, তখন defaultRuleSyntax এবং যেকোনো ruleSyntax লেবেল ডিলিট করুন, Traefik রিস্টার্ট করুন, এবং নিশ্চিত করুন যে প্রতিটি রাউটার ড্যাশবোর্ডে সবুজ দেখাচ্ছে। 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

দুটি লেবেল পরিবর্তিত হয়েছে। নিয়মটি (rule) এর multi-value Host-কে || দিয়ে যুক্ত দুটি matcher-এ বিভক্ত করেছে এবং placeholder-টির পরিবর্তে PathRegexp ব্যবহার করেছে; এছাড়া middleware লেবেলে ipwhitelist এর পরিবর্তে ipallowlist ব্যবহার করা হয়েছে। entrypoint, certificate resolver, router-to-middleware wiring, এবং service port অপরিবর্তিত রয়েছে।

Dashboard দিয়ে প্রতিটি service পরীক্ষা করুন

প্রতিটি flip করার পর, dashboard-এর HTTP routers পেজটি খুলুন। প্রতিটি router সবুজ রঙের হওয়া উচিত। যদি কোনো router-এ error badge থাকে, তবে সেটি সমস্যার সঠিক কারণ দেখাবে। সাধারণত এটি এমন একটি middleware যা নতুন নামে নেই অথবা এমন একটি rule যা v3 parse করতে পারছে না। এরপর বাইরে থেকে প্রতিটি 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 সততা

v3 সংস্করণে প্রতিটি service সঠিকভাবে route করছে এবং সঠিকভাবে কাজ করছে তা নিশ্চিত না করা পর্যন্ত v2 compose file, এর static configuration এবং acme.json backup সংরক্ষণ করুন। Rollback করার অর্থ হলো migration-এর আগের commit চেক আউট করা এবং docker compose up -d চালানো। এটি সম্পূর্ণ file হতে হবে, শুধুমাত্র image tag নয়। কারণ v3-এর জন্য নির্ধারিত labels গুলো v2-এর জন্য সঠিক নয়; ঠিক যেভাবে v2-এর labels গুলো v3-এর জন্য ভুল ছিল। v2 সংস্করণে ipallowlist নেই এবং সেখানে PathRegexp matcher কাজ করবে না। যদি এই প্রক্রিয়ায় acme.json হারিয়ে যায় বা ক্ষতিগ্রস্ত হয়, তবে v2 শুরু করার আগে backup copyটি restore করুন। এতে rollback করার সময় Let's Encrypt rate limit শেষ হয়ে যাবে না, কারণ একসাথে পাঁচটি certificate পুনরায় ইস্যু করতে হবে।

FAQ

Traefik v3-এর জন্য কি আমাকে প্রতিটি router rule পুনরায় লিখতে হবে?

না। backticks ব্যবহার করে লেখা সাধারণ Host(app.example.com) rule উভয় ভার্সনেই বৈধ, যা বেশিরভাগ Compose setup-এর জন্য যথেষ্ট। শুধুমাত্র সেই ক্ষেত্রে পুনরায় লেখার প্রয়োজন হবে যেখানে rule-এ v2-এর নির্দিষ্ট ফিচার ব্যবহৃত হয়েছে: যেমন Path এবং PathPrefix-এর ভেতরে regex বা placeholders, একটি Host()-এর ভেতরে একাধিক hostname, backticks-এর পরিবর্তে quotes, অথবা বাদ দেওয়া হয়েছে এমন Headers, HeadersRegexp, এবং HostHeader matchers।

Traefik v3-এ ipWhiteList-এর কী হয়েছে?

এর নাম পরিবর্তন করে ipAllowList করা হয়েছে, তবে এর ভেতরের configuration অপরিবর্তিত রয়েছে। তাই v2-এর traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 label-টি ipallowlist সহ একই লাইনে রূপান্তরিত হয়। বর্তমান v3 রিলিজগুলো (v3.5 সহ) এখনও পুরনো নামটি deprecated alias হিসেবে গ্রহণ করে, তাই নাম পরিবর্তন না করলেও allowlist কার্যকর থাকে। এটিকে পরিবর্তনের বিকল্প হিসেবে না দেখে সাময়িক সুবিধা হিসেবে বিবেচনা করুন: এই aliasটি সরিয়ে ফেলার পরিকল্পনা করা হয়েছে। Traefik যদি কোনো middleware নাম চিনতে না পারে, তবে সেটি router error এবং 404 এর মাধ্যমে স্পষ্টভাবে ব্যর্থতা প্রদর্শন করবে। dashboard-এ error দেখা যাবে এবং ওই hostname-এ করা request-গুলো 404 রিটার্ন করবে।

Traefik v3 কি এখনও v2 rule syntax পড়তে পারে?

হ্যাঁ। মাইগ্রেশনের সময় v2 syntax ডিফল্ট হিসেবে রাখতে static configuration-এ core.defaultRuleSyntax: v2 সেট করুন। ডিফল্ট পুনরায় পরিবর্তন করার পর প্রতিটি আলাদা router-এর জন্য ruleSyntax=v2 label ব্যবহার করুন। উভয়কেই সাময়িক হিসেবে বিবেচনা করুন: Traefik v3.4-এ এগুলোকে deprecated ঘোষণা করেছে এবং পরবর্তী major version-এ এগুলো সরিয়ে ফেলবে।

আপগ্রেড করার পর কি আমার Let's Encrypt certificates গুলো থাকবে?

হ্যাঁ। Traefik v3 এখনও v2 দ্বারা লেখা acme.json ফাইলটি পড়তে পারে, তাই শুধুমাত্র binary পরিবর্তন হওয়ার কারণে certificate পুনরায় ইস্যু করার প্রয়োজন হয় না। কাজ শুরু করার আগে ফাইলটি নিরাপদ কোনো স্থানে কপি করে রাখুন; কারণ rollback করা হলে বা কোনো volume ডিলিট হয়ে গেলে acme.json হারিয়ে যেতে পারে, যা সব certificate একসাথে পুনরায় ইস্যু করতে বাধ্য করবে। Let's Encrypt একই hostname সেটের জন্য প্রতি সপ্তাহে মাত্র পাঁচটি duplicate certificate ইস্যু করার অনুমতি দেয়।

আপগ্রেড করার পর Traefik v3 কেন স্টার্ট হতে ব্যর্থ হয়?

প্রায় সব ক্ষেত্রেই এর কারণ হলো static configuration-এ এখনও এমন কোনো option আছে যা v3 থেকে সরিয়ে ফেলা হয়েছে। Traefik অপরিচিত option থাকলে স্টার্ট হতে অস্বীকার করে। পরিচিত কিছু অবশিষ্টাংশের (pilot, providers.docker.swarmMode, experimental.http3) ক্ষেত্রে log-এ incompatible deprecated static option found দেখাবে এবং দোষী option-টির নাম জানাবে; আর v3 আগে কখনো দেখেনি এমন কিছুর ক্ষেত্রে (যেমন tls.caOptional), এটি node সহ field not found দেখাবে। প্রতিটি option ডিলিট বা পরিবর্তন করুন, তারপর container টি পুনরায় স্টার্ট করুন।