Cara migrasi Traefik v2 ke v3 tanpa ralat

Perbezaan antara Traefik v2 dan v3

Migrasi daripada Traefik v2 ke v3 sebahagian besarnya adalah kerja penamaan semula. Perubahan yang paling utama adalah middleware ipWhiteList kini menjadi ipAllowList. Selain itu, v3 memperketat sintaks peraturan router ( PathPrefix kehilangan ciri regex, beberapa matcher ditukar nama atau dihapuskan), menghentikan beberapa provider dan pilihan secara terus, tetapi mengekalkan fungsi lain: entrypoints, tetapan sijil ACME, aliran kerja label Docker, dan acme.json anda tetap berfungsi. v3 juga menyediakan mod keserasian yang mengekalkan sintaks peraturan v2, supaya anda boleh menaik taraf binary terlebih dahulu dan menulis semula peraturan satu demi satu bagi setiap servis berbanding melakukan semuanya dalam satu malam yang berisiko.

Panduan ini mengandaikan penggunaan tetapan Docker Compose berasaskan label daripada panduan reverse proxy Traefik. Halaman tersebut adalah untuk v3; halaman ini adalah untuk sistem yang masih menjalankan tag traefik:v2.

Penamabahan nama dan pembuangan

• ipWhiteList kini adalah ipAllowList, untuk middleware HTTP dan TCP. Pilihan di dalamnya tidak berubah, jadi sourcerange mengekalkan maksud yang sama. Versi v3 semasa, termasuk v3.5, masih menerima nama lama sebagai alias yang telah usang (deprecated) dan masih menguatkuasakan senarai tersebut, jadi penamaan semula ini tidak akan merosakkan apa-apa. Tetap tukar nama tersebut: alias tersebut dijadualkan untuk dibuang, dan ia akan hilang daripada senarai usang secara senyap.
• providers.docker.swarmMode=true telah dibuang. Swarm kini mempunyai provider sendiri, yang dikonfigurasikan sebagai providers.swarm.endpoint.
• Bahagian pilot telah dibuang sepenuhnya.
• experimental.http3 telah dibuang. HTTP/3 kini diaktifkan terus pada entrypoint.
• tls.caOptional telah dibuang daripada provider dan daripada middleware forwardAuth.
• Provider metrik InfluxDB v1, provider Rancher, dan provider Marathon telah dibuang.
• Tracing telah berpindah ke OpenTelemetry. Backend tracing khusus, termasuk integrasi Jaeger dan Zipkin, telah dibuang, dan v3 mengeksport OTLP (protokol OpenTelemetry) sebagai ganti.
• Pilihan ssl* yang telah usang di dalam middleware headers (sslRedirect, sslHost, dan selebihnya) telah dibuang. Redireksi entrypoint dan middleware redirectScheme telah menggantikan pilihan tersebut.

Pembuangan ini lebih kritikal daripada yang dilihat, kerana Traefik akan gagal untuk bermula jika konfigurasi statik mengandungi pilihan yang tidak dikenali. Baris pilot atau swarmMode yang tertinggal akan menghentikan container semasa proses boot dengan mesej incompatible deprecated static option found yang menyatakan pilihan tersebut; pilihan yang tidak pernah didengar oleh Traefik (kesalahan ejaan, atau tls.caOptional) pula akan menghentikannya dengan mesej field not found. Bersihkan konfigurasi statik sebelum anda menukar tag imej.

Nama middleware yang benar-benar tidak dikenali oleh Traefik (kesalahan ejaan, atau nama yang dibuang dan bukannya dijadikan alias) akan gagal dengan cara berbeza: router yang merujuk kepadanya akan dimuatkan dengan ralat dan bukannya sebagai route, dashboard akan menandakannya, dan API akan melaporkan middleware "offce@docker" does not exist. Permintaan ke hostname tersebut akan menerima ralat 404 kerana router tidak berjaya dimuatkan. Sila ambil perhatian bahawa ipwhitelist BUKAN dalam kategori ini pada v3 semasa: ia kekal sebagai alias yang telah usang, jadi label yang tidak ditukar nama akan terus berfungsi secara senyap.

Perubahan sintaks peraturan

Peraturan adalah tempat penulisan semula sebenar berlaku. Perubahan dalam v3:

• Tanda backtick diperlukan untuk nilai di dalam matcher. v2 menerima tanda petikan berganda; v3 tidak, jadi Host("app.example.com") mesti ditukar kepada Host(app.example.com).
• PathPrefix tidak lagi memahami ekspresi regular atau placeholder gaya {id}. Peraturan v2 seperti PathPrefix(/api/{version:v[0-9]+}) mesti menjadi matcher PathRegexp yang ditulis dalam sintaks ekspresi regular Go.
• Matcher kini hanya menerima satu nilai. v2 membenarkan Host(app.example.com,www.example.com); v3 memerlukan Host(app.example.com) || Host(www.example.com). Pengecualian adalah Header, HeaderRegexp, Query, dan QueryRegexp, yang masih memerlukan nama beserta nilai.
• Headers dan HeadersRegexp telah ditukar nama kepada Header dan HeaderRegexp.
• HostHeader telah dibuang. Gunakan Host, yang memadankan perkara yang sama dalam v3.
• Dua matcher baharu telah ditambah: QueryRegexp, dan ClientIP untuk memadankan alamat klien di dalam peraturan.

Berita baik: peraturan Host(app.example.com) biasa yang ditulis dengan backtick sudah merupakan sintaks v3 yang sah. Kebanyakan tetapan Compose kecil menggunakan format tersebut, bermakna kebanyakan label boleh dipindahkan tanpa sebarang suntingan peraturan.

Audit label anda sebelum bermula

Anda boleh mengukur saiz migrasi dengan satu carian, kerana setiap perubahan label yang memecahkan sistem meninggalkan corak yang boleh ditemui oleh grep:

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

Setiap hasil padanan adalah satu baris yang perlu diedit. ipwhitelist menjadi ipallowlist. HostHeader menjadi Host. Headers menjadi Header. Placeholder {...} di dalam PathPrefix menjadi pemadanan PathRegexp. Koma di dalam Host() menjadi dua pemadanan Host() yang disambungkan oleh ||. Sifar hasil padanan bermaksud label anda sudah menggunakan sintaks v3 yang sah, dan migrasi hanya melibatkan konfigurasi statik serta tag imej.

Apa yang kekal sama

Entrypoint dan pemb redirection HTTP-ke-HTTPS, ACME resolver dengan kedua-dua jenis challenge, exposedByDefault, label router dan service, loadbalancer.server.port, serta dashboard semuanya berfungsi dalam v3 seperti dalam v2. Sijil anda juga akan dibawa bersama, kerana v3 terus membaca acme.json yang ditulis oleh v2. Walau bagaimanapun, buat salinan sandaran (backup) fail tersebut sebelum bermula, kerana proses rollback yang menyebabkan kehilangan fail tersebut akan menyebabkan anda terkena had kadar (rate limit) sijil pendua Let's Encrypt:

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

Laluan migrasi

Langkah 1: tetapkan versi yang anda gunakan sekarang. Tukar mana-mana tag traefik:latest atau traefik:v2 kepada versi tepat yang anda gunakan, contohnya traefik:v2.11, dan lakukan commit pada keseluruhan direktori compose ke git. Setiap langkah seterusnya boleh dibatalkan dengan melakukan checkout. Jika membina semula perkhidmatan tunggal dengan docker compose up -d <service> belum mahir, panduan asas Docker Compose merangkumi operasi yang digunakan dalam migrasi ini.

Langkah 2: bersihkan konfigurasi statik dan aktifkan mod keserasian. Buang setiap pilihan yang telah digugurkan oleh v3 (pilot, swarmMode, tls.caOptional, experimental.http3), kemudian arahkan v3 untuk melayan peraturan sebagai sintaks v2 secara lalai. Dalam traefik.yml:

core:
  defaultRuleSyntax: v2

Atau sebagai flag dalam senarai compose command:: --core.defaultRuleSyntax=v2. Mod keserasian hanya merangkumi sintaks peraturan. Ia tidak menghidupkan semula pilihan yang telah dibuang, dan ia tidak menamakan semula middleware untuk anda.

Langkah 3: sediakan penamaan semula middleware. Cari nama lama dalam fail compose anda: grep -rn ipwhitelist docker-compose*.yml. Edit setiap label ipwhitelist kepada ipallowlist, tetapi jangan laksanakan perubahan tersebut lagi, kerana nama baharu tidak wujud dalam v2. Suntingan ini akan dilaksanakan bersama-sama dengan pertukaran pada langkah seterusnya. (Jika ada yang terlepas, v3 semasa masih menghormati nama lama sebagai alias yang telah usang, jadi senarai tersebut tetap dikuatkuasakan; perbaiki pada pusingan seterusnya berbanding pada jam 2 pagi.)

Langkah 4: tukar tag imej. Tetapkan imej Traefik kepada versi v3 semasa, traefik:v3.5 pada masa penulisan ini, kemudian:

docker compose up -d
docker compose logs -f traefik

Kerana mod keserasian telah diaktifkan, peraturan v2 anda tetap sepadan, dan kerana up -d juga membina semula perkhidmatan yang label middlewarenya telah anda namakan semula, router tersebut akan berfungsi dengan bersih. Log yang sihat tidak mempunyai baris field not found dan tiada baris does not exist.

Fahami risiko tempoh masa yang dibuka oleh langkah ini. Router yang merujuk kepada nama middleware yang tidak dikenali oleh v3 (kesalahan taip, atau pilihan yang telah dibuang) akan tergendala bermula dari saat Traefik baharu bermula sehingga kontena aplnya dibina semula, yang pada satu mesin mengambil masa beberapa saat docker compose up -d untuk memproses senarai tersebut. Jika sesuatu laluan benar-benar tidak boleh tergendala, buang middleware yang telah dinamakan semula daripada label middlewares router tersebut sebelum pertukaran dan tambah semula selepas itu, dan tentukan lebih awal sama ada laluan tersebut boleh berfungsi tanpa senarai benarkan IP (IP allow list) untuk tempoh seminit di antaranya.

Langkah 5: migrasi peraturan per perkhidmatan. Lakukan satu apl pada satu masa: tulis semula peraturannya kepada sintaks v3, bina semula perkhidmatan itu sahaja dengan docker compose up -d app, dan uji sebelum beralih ke langkah seterusnya. Jika satu perkhidmatan mempunyai peraturan yang belum boleh ditulis semula, berikan router tunggal tersebut label jalan keluar traefik.http.routers.app.ruleSyntax=v2 dan teruskan proses.

Langkah 6: matikan mod keserasian. Apabila setiap peraturan adalah sintaks v3, padam defaultRuleSyntax dan mana-mana label ruleSyntax, mulakan semula Traefik, dan sahkan setiap router masih menunjukkan status hijau dalam dashboard. Jangan terus menggunakan mod keserasian: Traefik telah mengisytiharkan kedua-dua pilihan tersebut sebagai usang dalam v3.4 dan akan membuangnya dalam versi utama seterusnya, jadi ia hanyalah jambatan, bukan destinasi akhir.

Sebelum dan selepas: label bagi satu servis

Berikut adalah satu aplikasi yang mengandungi semua perubahan utama secara serentak: Host pelbagai nilai, placeholder PathPrefix, dan middleware ipWhiteList. Blok 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

Dan servis yang sama telah migrasi ke 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

Dua label telah berubah. Peraturan tersebut membahagikan Host pelbagai nilainya kepada dua matcher yang disambungkan oleh || dan menggantikan placeholder dengan PathRegexp, manakala label middleware menggantikan ipwhitelist dengan ipallowlist. Entrypoint, resolver sijil, sambungan router-ke-middleware, dan port servis tidak berubah.

Uji setiap perkhidmatan dengan dashboard

Selepas setiap pertukaran, buka halaman HTTP routers pada dashboard. Setiap router sepatutnya berwarna hijau. Router dengan lencana ralat akan menyatakan masalah tepatnya, yang biasanya disebabkan oleh middleware yang tidak wujud di bawah nama baharunya atau peraturan yang tidak dapat dibaca oleh v3. Kemudian sahkan dari luar, satu hostname pada satu masa:

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

200 atau penghalaan semula (redirect) biasa aplikasi anda bermaksud routing dan TLS kedua-duanya berjaya. 404 daripada Traefik bermaksud router tidak berfungsi; kembali ke dashboard dan baca ralatnya. Biarkan docker compose logs -f traefik terbuka dalam terminal kedua semasa anda bekerja, kerana setiap kegagalan parsing akan muncul di situ sebaik sahaja kontena dimulakan semula.

Integriti Rollback

Simpan fail compose v2, konfigurasi statiknya, dan sandaran acme.json sehingga setiap perkhidmatan menggunakan v3 dan telah diuji sepenuhnya. Proses rollback bermaksud melakukan checkout pada commit sebelum migrasi dan menjalankan docker compose up -d. Anda mesti menggunakan keseluruhan fail, bukan sekadar tag imej. Label khusus v3 akan menyebabkan ralat pada v2, sama seperti ralat label v2 pada v3: ipallowlist tidak wujud dalam v2, dan pemadan PathRegexp juga tidak boleh diproses di sana. Jika acme.json hilang atau rosak semasa proses, pulihkan salinan sandaran sebelum memulakan v2. Ini bagi mengelakkan proses rollback menggunakan had kadar Let's Encrypt untuk mengeluarkan semula lima sijil secara serentak.

FAQ

Adakah saya perlu menulis semula setiap peraturan router untuk Traefik v3?

Tidak. Peraturan Host(app.example.com) biasa yang ditulis dengan backticks adalah sah dalam kedua-dua versi, dan ini merangkumi kebanyakan tetapan Compose. Penulisan semula hanya diperlukan jika peraturan menggunakan ciri khusus v2: regex atau placeholder di dalam Path dan PathPrefix, beberapa hostname dalam satu Host(), penggunaan tanda petik berbanding backticks, atau matcher Headers, HeadersRegexp, dan HostHeader yang telah dibuang.

Apa yang berlaku kepada ipWhiteList dalam Traefik v3?

Ia telah ditukar nama kepada ipAllowList, dengan konfigurasi di dalamnya tidak berubah, jadi label v2 seperti traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 menjadi baris yang sama dengan ipallowlist di dalamnya. Versi v3 semasa, termasuk v3.5, masih menerima nama lama sebagai alias yang telah usang, jadi label yang tidak ditukar nama akan terus menguatkuasakan senarai benarkan (allowlist) secara senyap. Anggap ini sebagai tempoh peralihan dan bukannya alasan untuk mengabaikan penukaran nama: alias tersebut dijadualkan untuk dibuang, dan nama middleware yang tidak dikenali oleh Traefik akan menyebabkan kegagalan nyata dengan ralat router dan 404. Dashboard akan memaparkan ralat tersebut, dan permintaan ke hostname tersebut akan mengembalikan 404.

Bolehkah Traefik v3 masih membaca sintaks peraturan v2?

Ya. Tetapkan core.defaultRuleSyntax: v2 dalam konfigurasi statik untuk mengekalkan sintaks v2 sebagai lalai semasa anda melakukan migrasi, dan gunakan label ruleSyntax=v2 pada setiap router untuk baki peraturan yang belum dikemas kini selepas anda menukar semula tetapan lalai. Anggap kedua-duanya sebagai sementara: Traefik telah mengisytiharkan ia sebagai usang dalam v3.4 dan akan membuangnya dalam versi utama yang seterusnya.

Adakah sijil Let's Encrypt saya akan selamat selepas naik taraf?

Ya. Traefik v3 terus membaca fail acme.json yang ditulis oleh v2, jadi sijil tidak akan dikeluarkan semula hanya kerana fail binari telah berubah. Walau bagaimanapun, salin fail tersebut ke tempat yang selamat sebelum anda bermula, kerana proses rollback atau pemadaman volume yang menyebabkan kehilangan acme.json akan memaksa semua sijil dikeluarkan semula secara serentak, dan Let's Encrypt hanya membenarkan lima sijil pendua seminggu untuk set hostname yang sama.

Mengapa Traefik v3 gagal untuk bermula selepas naik taraf?

Hampir sentiasa disebabkan oleh konfigurasi statik yang masih mengandungi pilihan yang telah dibuang oleh v3, dan Traefik enggan bermula jika terdapat pilihan yang tidak dikenali. Untuk sisa konfigurasi yang biasa (pilot, providers.docker.swarmMode, experimental.http3), log akan menyatakan incompatible deprecated static option found dan menamakan punca masalah; untuk apa-apa yang tidak pernah dikenali oleh v3, seperti tls.caOptional, ia akan menyatakan field not found bersama nod tersebut. Padam atau gantikan setiap satu, kemudian mulakan semula kontena tersebut.