วิธีอัปเกรด Traefik v2 เป็น v3 พร้อมจุดที่ต้องแก้ไข

ความเปลี่ยนแปลงระหว่าง Traefik v2 และ v3

การย้ายจาก Traefik v2 ไปยัง v3 ส่วนใหญ่เป็นการเปลี่ยนชื่อ โดยสิ่งที่เห็นได้ชัดคือ middleware ชื่อ ipWhiteList ได้เปลี่ยนเป็น ipAllowList นอกจากนี้ v3 ยังปรับปรุงไวยากรณ์ของ router rule ให้เข้มงวดขึ้น (PathPrefix ไม่รองรับฟีเจอร์ regex อีกต่อไป และมีการเปลี่ยนชื่อหรือถอดตัวจับคู่บางรายการออก) รวมถึงยกเลิกการรองรับ provider และตัวเลือกบางอย่างโดยสิ้นเชิง แต่ส่วนประกอบอื่นยังคงทำงานได้ตามปกติ ไม่ว่าจะเป็น entrypoints, การตั้งค่า ACME certificate, เวิร์กโฟลว์ของ Docker labels และ acme.json ของคุณ ทั้งหมดนี้สามารถใช้งานต่อได้ทันที นอกจากนี้ v3 ยังมาพร้อมกับโหมดความเข้ากันได้ (compatibility mode) ที่ช่วยให้ไวยากรณ์ของ rule ใน v2 ยังคงทำงานได้ คุณจึงสามารถอัปเกรด binary ก่อน แล้วค่อยทยอยปรับแก้ rule ทีละบริการแทนการแก้ไขทั้งหมดในคราวเดียวซึ่งมีความเสี่ยงสูง

คู่มือนี้อ้างอิงการตั้งค่าผ่าน Docker Compose โดยใช้ labels จาก คู่มือ Traefik reverse proxy หน้าดังกล่าวเป็นเนื้อหาสำหรับ v3 โดยเฉพาะ ส่วนหน้านี้จัดทำขึ้นสำหรับเซิร์ฟเวอร์ที่ยังคงรันด้วย tag traefik:v2 อยู่

การเปลี่ยนชื่อและการนำออก

• ipWhiteList ถูกเปลี่ยนเป็น ipAllowList แล้ว ทั้งสำหรับ HTTP และ TCP middleware ตัวเลือกภายในยังคงเหมือนเดิม ดังนั้น sourcerange จึงยังคงความหมายเดิมทุกประการ รุ่น v3 ปัจจุบัน รวมถึง v3.7 ยังคงยอมรับชื่อเก่าในฐานะ alias ที่เลิกใช้งานแล้ว (deprecated) และยังคงบังคับใช้รายการดังกล่าว โดยจะบันทึกคำเตือนเรื่องการเลิกใช้งานไว้ ดังนั้นการเปลี่ยนชื่อนี้จะไม่ทำให้ระบบหยุดทำงานแต่อย่างใด อย่างไรก็ตาม ควรเปลี่ยนชื่อไว้เนื่องจากชื่อเก่าถูกเลิกใช้งานแล้ว และ v2.11 ก็รองรับ ipAllowList แล้ว ดังนั้นจึงสามารถเปลี่ยนชื่อก่อนการอัปเกรดได้
• providers.docker.swarmMode=true ถูกนำออกแล้ว Swarm จะมี provider ของตัวเอง ซึ่งกำหนดค่าเป็น providers.swarm.endpoint
• ส่วน pilot ถูกนำออกไปทั้งหมด
• experimental.http3 ถูกนำออกแล้ว โดย HTTP/3 จะถูกเปิดใช้งานที่ entrypoint โดยตรง
• tls.caOptional ถูกนำออกจาก provider และจาก forwardAuth middleware หาก middleware ดังกล่าวอยู่หน้า ระบบ Authentik SSO ที่โฮสต์เอง การลบบรรทัด caOptional ออกถือเป็นการย้ายระบบที่สมบูรณ์สำหรับส่วนนี้ เนื่องจากที่อยู่ forwardAuth, trusted headers และ outpost ที่อยู่เบื้องหลังทั้งหมดทำงานเหมือนเดิมใน v3
• InfluxDB v1 metrics provider, Rancher provider และ Marathon provider ถูกนำออกแล้ว
• ระบบ Tracing ถูกย้ายไปใช้ OpenTelemetry แล้ว โดย backends เฉพาะสำหรับ tracing รวมถึงการเชื่อมต่อกับ Jaeger และ Zipkin ถูกนำออกไป และ v3 จะส่งออกข้อมูลผ่าน OTLP (OpenTelemetry protocol) แทน
• ตัวเลือก ssl* ที่เลิกใช้งานแล้วภายใน headers middleware (sslRedirect, sslHost และส่วนที่เหลือ) ถูกนำออกแล้ว โดยมีการใช้การเปลี่ยนเส้นทางที่ entrypoint และ redirectScheme middleware มาแทนที่

การนำออกเหล่านี้มีความสำคัญมากกว่าที่เห็น เนื่องจาก Traefik จะไม่ยอมเริ่มทำงานหาก static configuration มีตัวเลือกที่ถูกนำออกไปหรือตัวเลือกที่ระบบไม่รู้จัก บรรทัด pilot, swarmMode, experimental.http3 หรือ provider tls.caOptional ที่หลงเหลืออยู่จะทำให้ container หยุดทำงานทันทีที่บูต: Traefik จะบันทึกบรรทัดที่ระบุถึงสิ่งที่หลงเหลืออยู่ก่อน (เช่น ตัวเลือก Docker provider tls.CAOptional ถูกนำออกใน v3) จากนั้นจะล้มเหลวด้วย incompatible deprecated install configuration option found สำหรับรุ่น v3.4 ลงไป ข้อความสุดท้ายจะแสดงเป็น incompatible deprecated static option found ส่วนตัวเลือกที่ Traefik ไม่รู้จักเลย เช่น การพิมพ์ผิด จะทำให้ระบบหยุดทำงานพร้อมกับ field not found และโหนดแทน ดังนั้นควรทำความสะอาด static configuration ก่อนที่จะเปลี่ยน image tag

ชื่อ middleware ที่ Traefik ไม่รู้จักจริงๆ (เช่น การพิมพ์ผิด หรือชื่อที่ถูกนำออกไปโดยไม่มี alias) จะทำให้เกิดความล้มเหลวในรูปแบบที่ต่างออกไป: router ที่อ้างอิงถึง middleware นั้นจะโหลดพร้อมกับข้อผิดพลาดแทนที่จะโหลดเส้นทางปกติ dashboard จะทำเครื่องหมายไว้ และ API จะรายงาน middleware "offce@docker" does not exist คำขอที่ส่งไปยัง hostname นั้นจะได้รับ 404 เนื่องจาก router ไม่ได้เริ่มทำงาน โปรดทราบว่า ipwhitelist ไม่อยู่ในหมวดหมู่นี้ใน v3 ปัจจุบัน: มันยังคงอยู่เป็น alias ที่เลิกใช้งานแล้ว ดังนั้น label ที่ไม่ได้เปลี่ยนชื่อจะยังคงทำงานได้ตามปกติ

การเปลี่ยนแปลงไวยากรณ์ของกฎ

กฎ (Rules) คือส่วนที่การเขียนคำขอใหม่ (rewriting) เกิดขึ้นจริง การเปลี่ยนแปลงใน v3 มีดังนี้:

• การใช้เครื่องหมายคำพูดไม่มีการเปลี่ยนแปลง ทั้งสองเวอร์ชันรับค่าในกฎที่อยู่ใน backtick หรือ double quote ที่มีการ escape และปฏิเสธ single quote ดังนั้น Host(app.example.com) และ Host("app.example.com") ที่ใช้ double quote แบบ escape ยังคงใช้งานได้ตามปกติ
• PathPrefix ไม่รองรับ regular expression หรือตัวแทนค่าแบบ {id} อีกต่อไป กฎ v2 เช่น PathPrefix(/api/{version:v[0-9]+}) จะต้องเปลี่ยนเป็นตัวจับคู่ (matcher) แบบ PathRegexp ที่เขียนด้วยไวยากรณ์ regular expression ของภาษา Go
• ตัวจับคู่ในปัจจุบันรับค่าได้เพียงค่าเดียว 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
• มีตัวจับคู่ใหม่สองรายการคือ PathRegexp และ QueryRegexp ส่วน ClientIP สำหรับการจับคู่ที่อยู่ของไคลเอนต์ภายในกฎนั้นมีอยู่แล้วตั้งแต่ v2.11 และยังคงใช้งานได้โดยไม่มีการเปลี่ยนแปลง

ข่าวดีคือ กฎ Host(app.example.com) แบบพื้นฐานที่เขียนด้วย backtick เป็นไวยากรณ์ที่ถูกต้องสำหรับ v3 อยู่แล้ว การตั้งค่า Compose ขนาดเล็กส่วนใหญ่ใช้รูปแบบนี้ ซึ่งหมายความว่า label ส่วนใหญ่สามารถย้ายระบบได้โดยไม่ต้องแก้ไขกฎเลยแม้แต่น้อย

ตรวจสอบป้ายกำกับของคุณก่อนเริ่มดำเนินการ

คุณสามารถประเมินขนาดของการย้ายระบบได้ด้วยการค้นหาเพียงครั้งเดียว เนื่องจากทุกการเปลี่ยนแปลงป้ายกำกับที่ทำให้เกิดความไม่เข้ากันจะทิ้งรูปแบบที่ grep สามารถตรวจพบได้:

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

ทุกผลลัพธ์ที่พบคือหนึ่งบรรทัดที่ต้องแก้ไข ipwhitelist จะกลายเป็น ipallowlist ส่วน HostHeader จะกลายเป็น Host และ Headers จะกลายเป็น Header ตัวยึดตำแหน่ง {...} ภายใน PathPrefix จะกลายเป็นตัวจับคู่ PathRegexp เครื่องหมายจุลภาคภายใน Host() จะกลายเป็นตัวจับคู่ Host() สองตัวที่เชื่อมกันด้วย || หากไม่พบผลลัพธ์ใดๆ หมายความว่าป้ายกำกับของคุณใช้ไวยากรณ์ v3 ที่ถูกต้องอยู่แล้ว และการย้ายระบบจะเหลือเพียงการตั้งค่าแบบคงที่รวมถึงแท็กของอิมเมจเท่านั้น หากหน้าจอเต็มไปด้วยผลลัพธ์ที่พบ นี่เป็นช่วงเวลาที่เหมาะสมในการพิจารณาว่านี่ยังคงเป็น proxy ที่เหมาะสมสำหรับเซิร์ฟเวอร์นี้หรือไม่ และ การเปรียบเทียบ Traefik กับ Nginx และ Caddy จะช่วยให้คุณนำต้นทุนในการเขียนใหม่นี้ไปเปรียบเทียบกับสิ่งที่อีกสองตัวเลือกต้องการจากคุณในแต่ละแอปพลิเคชัน

สิ่งที่ยังคงเหมือนเดิม

Entrypoints และการเปลี่ยนเส้นทาง HTTP-to-HTTPS, ACME resolvers ที่รองรับทั้งสอง challenge types, exposedByDefault, router และ service labels, loadbalancer.server.port รวมถึง dashboard ทั้งหมดทำงานใน v3 ได้เช่นเดียวกับใน v2 ใบรับรองของคุณสามารถนำมาใช้ต่อได้ เนื่องจาก v3 ยังคงอ่านไฟล์ acme.json ที่ v2 สร้างไว้ อย่างไรก็ตาม ให้สำรองไฟล์ดังกล่าวก่อนเริ่มดำเนินการเสมอ เนื่องจากการย้อนกลับ (rollback) ที่ทำให้ไฟล์สูญหายจะส่งผลให้คุณติดข้อจำกัดอัตราการออกใบรับรองซ้ำ (duplicate-certificate rate limit) ของ Let's Encrypt ทันที:

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

เส้นทางการย้ายระบบ

ขั้นตอนที่ 1: ตรึงเวอร์ชันที่ใช้งานอยู่ในปัจจุบัน เปลี่ยนแท็ก traefik:latest หรือ traefik:v2 ให้เป็นเวอร์ชันที่คุณใช้งานอยู่จริง เช่น traefik:v2.11 แล้ว commit ไดเรกทอรี compose ทั้งหมดลงใน git ทุกขั้นตอนหลังจากนี้จะสามารถย้อนกลับได้ด้วยการ checkout หากการสร้างบริการใหม่ด้วย docker compose up -d <service> ยังไม่คล่องตัว คู่มือพื้นฐาน Docker Compose ได้ครอบคลุมการทำงานที่จำเป็นสำหรับการย้ายระบบครั้งนี้ไว้แล้ว

ขั้นตอนที่ 2: ทำความสะอาดการตั้งค่าแบบ static และเปิดโหมดความเข้ากันได้ ลบตัวเลือกที่ถูกตัดออกใน v3 ทั้งหมด (pilot, swarmMode, tls.caOptional, experimental.http3) จากนั้นกำหนดให้ v3 ปฏิบัติต่อกฎต่างๆ เป็นไวยากรณ์ v2 โดยค่าเริ่มต้น ในไฟล์ traefik.yml:

core:
  defaultRuleSyntax: v2

หรือระบุเป็นแฟล็กในรายการ command: ของ compose: --core.defaultRuleSyntax=v2 โหมดความเข้ากันได้จะครอบคลุมเฉพาะไวยากรณ์ของกฎเท่านั้น ไม่สามารถกู้คืนตัวเลือกที่ถูกลบไปแล้วได้ และไม่สามารถเปลี่ยนชื่อ middleware ให้คุณโดยอัตโนมัติ

ขั้นตอนที่ 3: เปลี่ยนชื่อ middleware ขณะที่ยังอยู่บน v2.11 ค้นหาชื่อเก่าในไฟล์ compose ของคุณ: grep -rn ipwhitelist docker-compose*.yml แก้ไข label ipwhitelist ทุกจุดให้เป็น ipallowlist และสร้างบริการเหล่านั้นใหม่ด้วย docker compose up -d เนื่องจาก v2.11 รองรับ middleware ชื่อ IPAllowList อยู่แล้ว การเปลี่ยนชื่อ label จึงใช้งานได้ก่อนการสลับเวอร์ชัน และคำเตือนเรื่องการเลิกใช้งาน IPWhiteList จะหายไปจาก log ของ v2 ของคุณ สำหรับเวอร์ชันที่เก่ากว่า v2.11 จะไม่รู้จักชื่อใหม่ ดังนั้นหากคุณตรึงเวอร์ชัน v2 ที่เก่ากว่าไว้ในขั้นตอนที่ 1 ให้ขยับไปที่ traefik:v2.11 ก่อน (หากมีจุดใดหลุดรอดไป v3 ในปัจจุบันยังคงยอมรับชื่อเก่าในฐานะ alias ที่ถูกเลิกใช้งาน ดังนั้นรายการดังกล่าวจะยังคงบังคับใช้กฎอยู่ ให้แก้ไขในรอบถัดไปแทนที่จะรีบแก้ไขในเวลาตี 2)

ขั้นตอนที่ 4: สลับแท็ก image ตั้งค่า image ของ Traefik ให้เป็นเวอร์ชัน v3 ปัจจุบัน คือ traefik:v3.7 ณ วันที่ 11 ตุลาคม 2026 (v3.7.14 คือแพตช์ล่าสุด) จากนั้น:

docker compose up -d
docker compose logs -f traefik

เนื่องจากเปิดโหมดความเข้ากันได้ไว้ กฎ v2 ของคุณจะยังคงทำงานได้ และเนื่องจากได้เปลี่ยนชื่อ middleware ไปแล้วตั้งแต่ตอนอยู่บน v2.11 เราเตอร์เหล่านั้นจึงทำงานได้ตามปกติ log ที่สมบูรณ์จะต้องไม่มีบรรทัด field not found และไม่มีบรรทัด does not exist

โปรดประเมินช่วงเวลาที่ระบบอาจหยุดทำงานในขั้นตอนนี้ให้ดี เราเตอร์ที่อ้างอิงชื่อ middleware ที่ v3 ไม่รู้จัก (เช่น พิมพ์ผิด หรือเป็นตัวเลือกที่ถูกลบไปแล้ว) จะหยุดทำงานทันทีที่ Traefik ใหม่เริ่มทำงาน จนกว่าคุณจะแก้ไข label และสร้าง container ของแอปนั้นใหม่ หากเส้นทางใดไม่สามารถหยุดทำงานได้เลย ให้ถอด middleware ที่น่าสงสัยออกจาก label middlewares ของเราเตอร์นั้นก่อนการสลับเวอร์ชัน แล้วค่อยเพิ่มกลับเข้าไปใหม่หลังจากนั้น และตัดสินใจล่วงหน้าว่าเส้นทางนั้นสามารถทำงานโดยไม่มี middleware ดังกล่าวได้หรือไม่ในช่วงเวลาสั้นๆ ระหว่างการสลับ

ขั้นตอนที่ 5: ย้ายกฎทีละบริการ ดำเนินการทีละแอป: เขียนกฎใหม่ให้เป็นไวยากรณ์ v3 สร้างบริการนั้นใหม่ด้วย docker compose up -d app และทดสอบก่อนที่จะดำเนินการต่อไป หากบริการใดมีกฎที่คุณยังไม่สามารถเขียนใหม่ได้ ให้ใส่ label traefik.http.routers.app.ruleSyntax=v2 ไว้ที่เราเตอร์นั้นเพื่อเป็นทางออกชั่วคราวแล้วดำเนินการต่อ

ขั้นตอนที่ 6: ปิดโหมดความเข้ากันได้ เมื่อกฎทุกตัวเป็นไวยากรณ์ v3 แล้ว ให้ลบ defaultRuleSyntax และ label ruleSyntax ออกทั้งหมด รีสตาร์ท Traefik และยืนยันว่าเราเตอร์ทุกตัวยังคงแสดงสถานะสีเขียวใน dashboard อย่าใช้งานโหมดความเข้ากันได้ค้างไว้นานเกินไป: Traefik ได้ประกาศเลิกใช้งานตัวเลือกทั้งสองนี้ใน v3.4 และจะลบออกในเวอร์ชันหลักถัดไป ดังนั้นมันจึงเป็นเพียงสะพานเชื่อม ไม่ใช่จุดหมายปลายทาง

ก่อนและหลัง: ป้ายกำกับ (labels) ของหนึ่งบริการ

นี่คือตัวอย่างแอปพลิเคชันที่รวมการเปลี่ยนแปลงสำคัญทุกรายการไว้ในที่เดียว ได้แก่ Host แบบหลายค่า, ตัวแทน (placeholder) PathPrefix และมิดเดิลแวร์ 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

มีการเปลี่ยนแปลงป้ายกำกับสองรายการ กฎดังกล่าวแยก Host แบบหลายค่าออกเป็นตัวจับคู่ (matcher) สองตัวที่เชื่อมด้วย || และเปลี่ยนตัวแทนเป็น PathRegexp ส่วนป้ายกำกับมิดเดิลแวร์ได้เปลี่ยนจาก ipwhitelist เป็น ipallowlist สำหรับ entrypoint, ตัวแก้ไขใบรับรอง (certificate resolver), การเชื่อมต่อ router-to-middleware และพอร์ตของบริการนั้นไม่มีการเปลี่ยนแปลงใดๆ

ทดสอบแต่ละบริการด้วยแดชบอร์ด

หลังจากสลับการตั้งค่าแต่ละครั้ง ให้เปิดหน้า HTTP routers ของแดชบอร์ด Router ทุกตัวควรแสดงสถานะเป็นสีเขียว หาก Router มีป้ายแจ้งเตือนข้อผิดพลาด ระบบจะระบุปัญหาที่เกิดขึ้นโดยตรง ซึ่งมักเกิดจาก middleware ที่ไม่มีอยู่จริงภายใต้ชื่อใหม่ หรือกฎที่ v3 ไม่สามารถประมวลผลได้ จากนั้นให้ตรวจสอบจากภายนอกทีละ hostname:

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

รหัสสถานะ 200 หรือการเปลี่ยนเส้นทางตามปกติของแอปพลิเคชัน หมายความว่าการกำหนดเส้นทางและ TLS ทำงานได้ตามปกติ หากได้รับ 404 จาก Traefik แสดงว่า Router ไม่สามารถเริ่มทำงานได้ ให้กลับไปที่แดชบอร์ดเพื่ออ่านข้อผิดพลาดนั้น เปิด docker compose logs -f traefik ทิ้งไว้ในเทอร์มินัลอีกหน้าต่างหนึ่งขณะที่คุณทำงาน เนื่องจากความล้มเหลวในการประมวลผลทุกครั้งจะปรากฏขึ้นที่นั่นทันทีที่ container เริ่มทำงานใหม่

ความซื่อสัตย์ในการย้อนกลับ (Rollback)

ให้เก็บไฟล์ compose เวอร์ชัน v2, การตั้งค่าแบบ static และไฟล์สำรองข้อมูล acme.json ไว้จนกว่าทุกบริการจะสามารถรับส่งข้อมูลบน v3 ได้และผ่านการทดสอบการใช้งานจริงแล้ว การย้อนกลับหมายถึงการ checkout commit ก่อนการย้ายระบบและรันคำสั่ง docker compose up -d ซึ่งต้องทำทั้งไฟล์ ไม่ใช่แค่การเปลี่ยน image tag เท่านั้น เนื่องจากไวยากรณ์ที่ใช้ได้เฉพาะใน v3 จะไม่ถูกต้องเมื่อใช้กับ v2 เช่นเดียวกับที่ไวยากรณ์ของ v2 ไม่สามารถใช้กับ v3 ได้ โดยตัวจับคู่ (matcher) PathRegexp จะไม่สามารถประมวลผลได้ในกรณีดังกล่าว สำหรับ label ipallowlist ที่ถูกเปลี่ยนชื่อนั้นสามารถใช้งานได้บน v2.11 แต่จะไม่รองรับใน v2 เวอร์ชันที่เก่ากว่านั้นเนื่องจากไม่รู้จักชื่อใหม่ หาก acme.json สูญหายหรือเสียหายระหว่างดำเนินการ ให้กู้คืนจากไฟล์สำรองก่อนเริ่มใช้งาน v2 เพื่อป้องกันไม่ให้การย้อนกลับใช้โควตาอัตราการออกใบรับรองของ Let's Encrypt จนหมดจากการพยายามออกใบรับรองใหม่ 5 รายการพร้อมกัน

FAQ

ฉันจำเป็นต้องเขียนกฎของ router ใหม่ทั้งหมดสำหรับ Traefik v3 หรือไม่?

ไม่จำเป็น กฎ Host(app.example.com) แบบปกติที่เขียนด้วย backticks สามารถใช้งานได้ทั้งสองเวอร์ชัน ซึ่งครอบคลุมการตั้งค่า Compose ส่วนใหญ่ การเขียนใหม่จำเป็นเฉพาะในกรณีที่กฎนั้นใช้ฟีเจอร์ที่มีเฉพาะใน v2 เท่านั้น เช่น regex หรือ placeholders ภายใน Path และ PathPrefix, การระบุชื่อโฮสต์หลายรายการภายใน Host() รายการเดียว หรือการใช้ matchers อย่าง Headers, HeadersRegexp และ HostHeader ที่ถูกถอดออกไปแล้ว

เกิดอะไรขึ้นกับ ipWhiteList ใน Traefik v3?

มันถูกเปลี่ยนชื่อเป็น ipAllowList โดยที่การตั้งค่าภายในยังคงเหมือนเดิม ดังนั้น label ของ v2 อย่าง traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 จึงกลายเป็นบรรทัดเดียวกันโดยมี ipallowlist อยู่ภายใน v2.11 รองรับชื่อใหม่นี้แล้ว คุณจึงสามารถเปลี่ยนชื่อก่อนทำการอัปเกรดได้ Traefik v3 เวอร์ชันปัจจุบัน รวมถึง v3.7 ยังคงยอมรับชื่อเก่าในฐานะ alias ที่ถูกเลิกใช้งาน (deprecated) ดังนั้น label ที่ยังไม่ได้เปลี่ยนชื่อจะยังคงบังคับใช้ allowlist ต่อไปโดยมีเพียงคำเตือนใน log เท่านั้น ให้ถือว่านี่เป็นเวลาที่ยืมเขามาใช้ ไม่ใช่เหตุผลที่จะละเลยการเปลี่ยนชื่อ เพราะชื่อที่ถูกเลิกใช้งานคือสิ่งที่ release ในอนาคตสามารถถอดออกได้ และหากเป็นชื่อ middleware ที่ Traefik ไม่รู้จักจริงๆ ระบบจะล้มเหลวอย่างชัดเจนด้วยข้อผิดพลาดที่ router และส่งผลให้เกิด 404 โดย dashboard จะแสดงข้อผิดพลาดดังกล่าว และคำขอไปยัง hostname นั้นจะได้รับผลลัพธ์เป็น 404

Traefik v3 ยังสามารถอ่านไวยากรณ์กฎของ v2 ได้หรือไม่?

ได้ ให้ตั้งค่า core.defaultRuleSyntax: v2 ใน static configuration เพื่อคงไวยากรณ์ของ v2 ไว้เป็นค่าเริ่มต้นในระหว่างที่คุณกำลังย้ายระบบ และใช้ label ruleSyntax=v2 ที่ระดับ router สำหรับรายการที่เหลือหลังจากที่คุณเปลี่ยนค่าเริ่มต้นกลับไปแล้ว ให้ถือว่าทั้งสองวิธีเป็นเพียงการแก้ปัญหาชั่วคราว เนื่องจาก Traefik ได้ประกาศเลิกใช้งาน (deprecated) ใน v3.4 และจะถอดออกในเวอร์ชันหลักถัดไป

certificate ของ Let's Encrypt ของฉันจะยังคงอยู่หลังการอัปเกรดหรือไม่?

ใช่ Traefik v3 ยังคงอ่านไฟล์ acme.json ที่ v2 เขียนไว้ ดังนั้น certificate จะไม่ถูกออกใหม่เพียงเพราะ binary เปลี่ยนไป อย่างไรก็ตาม ให้คัดลอกไฟล์ดังกล่าวไปยังที่ปลอดภัยก่อนเริ่มดำเนินการ เพราะการย้อนกลับ (rollback) หรือการลบ volume ที่ทำให้สูญเสีย acme.json จะบังคับให้ต้องออก certificate ใหม่ทั้งหมดพร้อมกัน ซึ่ง Let's Encrypt อนุญาตให้ขอ certificate ซ้ำได้เพียง 5 ฉบับต่อสัปดาห์สำหรับชุด hostname เดียวกัน

ทำไม Traefik v3 ถึงไม่ยอมเริ่มทำงานหลังการอัปเกรด?

เกือบทุกกรณีเกิดจาก static configuration ยังคงมีตัวเลือกที่ v3 ถอดออกไปแล้ว และ Traefik ปฏิเสธที่จะเริ่มทำงานหากพบตัวเลือกที่ไม่รู้จัก สำหรับรายการที่หลงเหลืออยู่ซึ่งเป็นที่ทราบกันดี (pilot, providers.docker.swarmMode, experimental.http3 และ tls.caOptional ของ providers) log จะระบุชื่อตัวการและตามด้วย incompatible deprecated install configuration option found (incompatible deprecated static option found ใน v3.4 และก่อนหน้า) สำหรับสิ่งใดก็ตามที่ v3 ไม่เคยรู้จักมาก่อน เช่น การพิมพ์ผิด ระบบจะแจ้งว่า field not found พร้อมระบุ node ให้ลบหรือแทนที่รายการเหล่านั้น แล้วเริ่ม container ใหม่อีกครั้ง