מה משתנה ב-Traefik v3 לעומת v2

מה משתנה בין Traefik v2 ל-v3

מעבר מ-Traefik v2 ל-v3 הוא בעיקר תהליך של שינוי שמות. השינוי המוכר ביותר הוא הפיכת ה-middleware בשם ipWhiteList ל-ipAllowList. מעבר לכך, v3 מחמירה בתחביר של ה-router rule (הפקודה PathPrefix מאבדת את יכולות ה-regex שלה, ומספר matchers שונו או הוסרו). גרסה זו גם מסירה מספר providers ואופציות, אך שומרת על שאר הפונקציות: entrypoints, הגדרת תעודות ACME, זרימת העבודה של Docker labels, וה-acme.json שלכם נשארים ללא שינוי. v3 כוללת גם מצב תאימות (compatibility mode) שמאפשר להמשיך להשתמש בתחביר הכללים של v2. כך ניתן לשדרג את ה-binary תחילה ולכתוב מחדש את הכללים עבור כל שירות בנפרד, במקום לבצע שינוי אחד מסוیس בערב אחד.

מדריך זה מניח שימוש בהגדרות Docker Compose מבוססות labels מתוך המדריך ל-Traefik reverse proxy. עמוד זה מותאם ל-v3; עמוד זה מיועד למערכות שעדיין מריצות תג traefik:v2.

שינויי שמות והסרות

• ipWhiteList הוא כעת ipAllowList, עבור ה-HTTP middleware וה-TCP middleware כאחד. האפשרויות בתוכו נותרו ללא שינוי, לכן המשמעות של sourcerange נשארת זהה. גרסאות v3 נוכחיות, כולל v3.5, עדיין מקבלות את השם הישן כ-deprecated alias וממשיכות לאכוף את הרשימה, לכן שינוי זה אינו גורם להפסקת פעילות. בכל זאת, יש לשנות את השם: ה-alias מתוכנן להסרה, והוא ייעלם מרשימת ה-deprecation ללא התראה מפורשת.
• providers.docker.swarmMode=true הוסר. ל-Swarm יש כעת provider משלו, המוגדר כ-providers.swarm.endpoint.
• סעיף ה-pilot הוסר לחלוטין.
• experimental.http3 הוסר. HTTP/3 מופעל ישירות ב-entrypoint.
• tls.caOptional הוסר מה-providers ומה-forwardAuth middleware.
• ה-InfluxDB v1 metrics provider, ה-Rancher provider, וה-Marathon provider הוסרו.
• ה-Tracing עבר ל-OpenTelemetry. ה-tracing backends הייעודיים, כולל ה-Jaeger וה-Zipkin integrations, הוסרו; גרסה v3 מייצאת OTLP (פרוטוקול OpenTelemetry) במקומם.
• האפשרויות ה-deprecated של ssl* בתוך ה-headers middleware (sslRedirect, sslHost ואחרות) הוסרו. ה-entrypoint redirections וה-redirectScheme middleware החליפו אותן.

הסרות אלו משמעותיות יותר מכפי שהן נראות, מכיוון ש-Traefik מסרב לעלות כאשר ה-static configuration מכיל אפשרות שאינו מכיר. שורה שנותרה של pilot או swarmMode תעצור את ה-container בזמן ה-boot עם הודעת incompatible deprecated static option found המציינת את האפשרות היתרה; אפשרות ש-Traefik מעולם לא הכיר (טעות הקלדה, או tls.caOptional) תעצור אותו עם הודעת field not found במקום זאת. יש לנקות את ה-static configuration לפני שינוי ה-image tag.

שם של middleware ש-Traefik אינו מכיר בפועל (טעות הקלדה, או שם שהוסר במקום שניתן לו alias) נכשל בצורה שונה: ה-router המתייחס אליו ייטען עם שגיאה במקום ליצור route, ה-dashboard יסמן זאת, וה-API ידווח על middleware "offce@docker" does not exist. בקשות ל-hostname זה יקבלו 404 מכיוון שה-router מעולם לא עלה. שים לב ש-ipwhitelist אינו שייך לקטגוריה זו בגרסת v3 הנוכחית: הוא נשאר כ-deprecated alias, ולכן label שלא שונה ימשיך לעבוד ללא הפרעה.

שינויים בתחביר הכללים (rule syntax)

כללים (rules) הם המקום שבו מתבצעת הכתיבה מחדש בפועל. השינויים ב-v3:

• יש להשתמש ב-backticks סביב ערכים בתוך matchers. ב-v2 נעשה שימוש גם בגרשיים כפולות; ב-v3 זה לא נתמך, לכן Host("app.example.com") חייב להפוść ל-Host(app.example.com).
• PathPrefix כבר אינו מבין regular expressions או placeholders בסגנון {id}. כלל v2 כגון PathPrefix(/api/{version:v[0-9]+}) חייב להפוך ל-matcher מסוג PathRegexp שנכתב בתחביר Go regular expression.
• 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 לצורך התאמת כתובת הלקוח (client address) בתוך כלל.

החדשות הטובות: כלל Host(app.example.com) פשוט שנכתב עם backticks הוא כבר תחביר v3 תקף. רוב הגדרות ה-Compose הקטנות משתמשות בדיוק בפורמט זה, מה שאומר שרוב ה-labels יעברו ללא צורך בעריכת כללים.

בדקו את התגים שלכם לפני ההתחלה

ניתן למדוד את נפח ההגירה באמצעות חיפוש אחד, מכיוון שכל שינוי שובר בתגים משאיר תבנית ש-grep יכול למצוא:

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

כל התאמה מייצגת שורה אחת שצריך לערוך. ipwhitelist הופך ל-ipallowlist. HostHeader הופך ל-Host. Headers הופך ל-Header. מקום (placeholder) מסוג {...} בתוך PathPrefix הופך למתאם (matcher) מסוג PathRegexp. פסיק בתוך Host() הופך לשני מתאמי Host() המחוברים באמצעות ||. אפס התאמות פירושו שהתגים שלכם כבר תקינים בתחביר v3, וההגירה תתמקד רק בהגדרות הסטטיות וב-image tag.

מה נשאר ללא שינוי

נקודות הכניסה (Entrypoints) והפניה מ-HTTP ל-HTTPS, מנגנוני ה-ACME resolvers עם שני סוגי ה-challenge, exposedByDefault, תוויות ה-router וה-service, loadbalancer.server.port, וה-dashboard, כולם עובדים ב-v3 בדיוק כפי שעבדו ב-v2. גם התעודות (certificates) שלך נשמרות, כיוון ש-v3 ממשיך לקרוא את ה-acme.json ש-v2 כתב. בכל מקרה, יש לגבות את הקובץ לפני תחילת העבודה, מכיוון שביצוע rollback שמוביל לאובדן הקובץ יגרום לחריגה מהמגבלה (rate limit) של Let's Encrypt עבור כפל תעודות:

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

The migration path

Step 1: pin what you run today. שנה כל תגית traefik:latest או traefik:v2 לגרסה המדויקת שבה אתה משתמש, לדוגמה traefik:v2.11, ובצע commit לכל ספריית ה-compose לתוך git. כל שלב מאוחר יותר יהיה ניתן לביטול באמצעות checkout. אם יצירה מחדש של שירות בודד באמצעות docker compose up -d <service> עדיין אינה ברורה לך, המדריך הבסיסי ל-Docker Compose מסביר את הפעולות שעליהן מסתמך תהליך הגירה זה.

Step 2: clean the static configuration and turn on compatibility mode. הסר כל אפשרות ש-v3 הפסיקה לתמוך בה (pilot, swarmMode, tls.caOptional, experimental.http3), ולאחר מכן הגדר ל-v3 להתייחס לכללים כסינטקס של v2 כברירת מחדל. בתוך traefik.yml:

core:
  defaultRuleSyntax: v2

או כ-flag ברשימת ה-compose command:: --core.defaultRuleSyntax=v2. מצב תאימות (compatibility mode) מכסה סינטקס של כללים בלבד. הוא אינו מחזיר אפשרויות שהוסרו, ואינו משנה את שמות ה-middlewares עבורך.

Step 3: prepare the middleware renames. חפש בקובצי ה-compose שלך את השמות הישנים: grep -rn ipwhitelist docker-compose*.yml. שנה כל תגית ipwhitelist ל-ipallowlist, אך אל תחיל את השינוי עדיין, מכיוון שהשם החדש אינו קיים ב-v2. עריכות אלו יוחלו יחד עם השינוי בשלב הבא. (אם תעבור טעות, גרסת v3 הנוכחית עדיין מכירה בשם הישן ככינוי מיושן, לכן הרשימה תמשיך להיות מבוקרת; תקן זאת בסבב הבא במקום בשעה 2 לפנות בוקר.)

Step 4: flip the image tag. הגדר את ה-image של Traefik לגרסת v3 הנוכחית, traefik:v3.5 בזמן כתיבת מדריך זה, ולאחר מכן:

docker compose up -d
docker compose logs -f traefik

מכיוון שמצב תאימות פעיל, הכללים של v2 שלך ימשיכו להתאים, ומכיוון ש-up -d יצר מחדש גם את השירותים שבהם שינית את תגיות ה-middleware, ה-routers יפעלו בצורה תקינה. לוג תקין לא יכיל שורת field not found ולא שורת does not exist.

היה מודע לחלון הזמן ששלב זה פותח. router שמפנה לשם middleware ש-v3 אינה מכירה (טעות הקלדה, או אפשרות שהוסרה) יהיה למטה מרגע הפעלת ה-Traefik החדש ועד ליצירה מחדש של ה-container של האפליקציה, מה שעל מכשיר אחד לוקח רק את שניות העבודה שdocker compose up -d זקוק להן כדי לעבור על הרשימה. אם נתיב (route) אינו יכול להפסיק לעבוד אפילו לרגע, הסר את ה-middleware ששונה שמו מתגית ה-middlewares של אותו router לפני השינוי, והוסף אותו מחדש לאחר מכן. החלט מראש האם אותו נתיב יכול להתקיים ללא רשימת ה-IP allow list שלו במהלך הדקה שביניהם.

Step 5: migrate rules service by service. עבוד על אפליקציה אחת בכל פעם: כתוב מחדש את הכלל שלה בסינטקס v3, צור מחדש רק את אותו שירות באמצעות docker compose up -d app, ובדוק אותו לפני המעבר לשירות הבא. אם לשירות מסוים יש כלל שעדיין אינך יכול לכתוב מחדש, תן ל-router הבודד הזה את תגית ה-escape hatch traefik.http.routers.app.ruleSyntax=v2 והמשך הלאה.

Step 6: turn compatibility mode off. כאשר כל כלל הוא בסינטקס v3, מחק את defaultRuleSyntax ואת כל תגיות ה-ruleSyntax, הפעל מחדש את Traefik, וודא שכל ה-routers עדיין מציגים מצב ירוק ב-dashboard. אל תתרגל לעבודה עם מצב תאימות פעיל: Traefik הפסיקה לתמוך בשתי האפשרויות בגרסה v3.4 ותסיר אותן בגרסה Major הבאה, לכן הן מהוות גשר ולא יעד סופי.

לפני ואחרי: labels של שירות אחד

להלן אפליקציה אחת הכוללת את כל השינויים המוכרים בבת אחת: Host רב-ערכי, placeholder מסוג PathPrefix, ו-middleware מסוג ipWhiteList. בלוק ה-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

שני labels השתנו. הכלל פיצל את ה-Host הרב-ערכי שלו לשני matchers המחוברים באמצעות ||, והחליף את ה-placeholder ב-PathRegexp. בנוסף, ה-middleware label החליף את ipwhitelist ב-ipallowlist. ה-entrypoint, ה-certificate resolver, הקישור בין ה-router ל-middleware, ופורט השירות לא השתנו.

בדיקת כל שירות באמצעות ה-dashboard

לאחר כל שינוי (flip), פתח את דף ה-HTTP routers ב-dashboard. כל router חייב להופיע בירוק. router עם סמל שגיאה (error badge) יציין את הבעיה המדויקת. בדרך כלל מדובר ב-middleware שלא קיים תחת שמו החדש, או בrule שגרסה v3 אינה יכולה לנתח (parse). לאחר מכן, ודא תקינות מבחוץ, עבור כל hostname בנפרד:

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

200 או הפניה (redirect) רגילה של האפליקציה שלך מעידים שגם ה-routing וגם ה-TLS תקינים. 404 מ-Traefik מעיד שה-router לא עלה; חזור ל-dashboard וקרא את השגיאה שלו. השאר את docker compose logs -f traefik פתוח בטרמינל שני בזמן העבודה, מכיוון שכל כשל בניתוח (parsing failure) יופיע שם ברגע שקונטיינר עובר restart.

Rollback honesty

שמור על קובץ ה-compose של v2, ההגדרות הסטטיות שלו, וגיבוי ה-acme.json עד שכל שירות ינתב דרך v3 ויעבור בדיקה בפועל. ביצוע rollback כולל מעבר ל-commit שלפני המעבר (pre-migration) והרצת docker compose up -d. יש להשתמש בקובץ המלא ולא רק ב-image tag, מכיוון ש-labels של v3-only אינם תקינים תחת v2, בדיוק כפי ש-labels של v2 לא היו תקינים תחת v3: ipallowlist אינו קיים ב-v2, וגם matcher מסוג PathRegexp לא יתפרס (parse) שם. אם acme.json אבד או ננזק במהלך התהליך, שחזר את עותק הגיבוי לפני הפעלת v2, כדי שה-rollback לא יבזבז את ה-rate limit של Let's Encrypt על הנפקת חמישה תעודות בבת אחת.

FAQ

האם אני חייב לכתוב מחדש כל חוק router עבור Traefik v3?

לא. חוק Host(app.example.com) פשוט שנכתב עם backticks הוא תקף בשתי הגרסאות, וזה מכסה את רוב הגדרות ה-Compose. כתיבה מחדש נדרשת רק במקרים שבהם חוק השתמש בתכונות של v2 בלבד: regex או placeholders בתוך Path ו-PathPrefix, מספר שמות מארחים בתוך Host() אחד, גרשיים במקום backticks, או ה-matchers שהוסרו: Headers, HeadersRegexp, ו-HostHeader.

מה קרה ל-ipWhiteList ב-Traefik v3?

היא שונתה ל-ipAllowList, כאשר ההגדרות בתוכה נשארו ללא שינוי. לכן, label של v2 כמו traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 יהפוך לאותה שורה עם ipallowlist בתוכה. גרסאות v3 נוכחיות, כולל v3.5, עדיין מקבלות את השם הישן כ-deprecated alias, ולכן label שלא שונה תמשיך לאכוף את ה-allowlist בשקט. התייחס לכך כזמן מוקדם ולא כסיבה לדלג על שינוי השם: ה-alias מתוכנן להסרה, ושם middleware ש-Traefik לא מכיר יגרום לשגיאה גורפת עם router error ו-404. ה-dashboard יציג את השגיאה, ובקשות לאותו hostname יחזירו 404.

האם Traefik v3 עדיין יכול לקרוא תחביר חוקים של v2?

כן. הגדר את core.defaultRuleSyntax: v2 ב-static configuration כדי לשמור על תחביר v2 כברירת מחדל בזמן המעבר, והשתמש ב-label ruleSyntax=v2 ברמת ה-router עבור חוקים בודדים לאחר שתחזיר את ברירת המחדל. התייחס לשניהם כפתרון זמני: Traefik הגדירה אותם כ-deprecated ב-v3.4 והם יוסרו בגרסה major הבאה.

האם תעודות Let's Encrypt שלי יישארו לאחר השדרוג?

כן. Traefik v3 ממשיך לקרוא את הקובץ acme.json שנכתב על ידי v2, לכן התעודות לא יונ kelu מחדש רק בגלל שה-binary השתנה. בכל מקרה, העתק את הקובץ למקום בטוח לפני שתתחיל, מכיוון ש-rollback או מחיקת volume שמוחקת את acme.json יאלצו הנפקת כל התעודות מחדש בבת אחת, ו-Let's Encrypt מאפשרת רק חמש תעודות כפולות בשבוע עבור אותו סט של hostnames.

מדוע Traefik v3 נכשל בהפעלה לאחר השדרוג?

כמעט תמיד בגלל שה-static configuration עדיין מכיל אפשרות ש-v3 הסירה, ו-Traefik מסרבת לעלות עם אפשרויות שהיא לא מזהה. עבור השאריות המוכרות (pilot, providers.docker.swarmMode, experimental.http3) הלוג יציג incompatible deprecated static option found ויציין את הגורם; עבור כל דבר ש-v3 לא הכירה מעולם, כגון tls.caOptional, הוא יציג field not found עם ה-node. מחק או החלף כל אפשרות כזו, ולאחר מכן הפעל את ה-container מחדש.