Cara migrasi Traefik v2 ke v3 tanpa ralat

Perubahan antara Traefik v2 dan v3

Migrasi daripada Traefik v2 ke v3 kebanyakannya melibatkan penamaan semula, dan penamaan semula yang paling ketara ialah middleware ipWhiteList yang kini menjadi ipAllowList. Selain itu, v3 memperketat sintaks peraturan router (PathPrefix tidak lagi menyokong ciri regex, beberapa matcher telah dinamakan semula atau dibuang), membuang beberapa provider dan pilihan secara terus, serta mengekalkan fungsi lain: entrypoints, tetapan sijil ACME, aliran kerja Docker labels, dan acme.json anda semuanya boleh dibawa terus. v3 juga menyertakan mod keserasian yang mengekalkan sintaks peraturan v2, jadi anda boleh menaik taraf binari terlebih dahulu dan menulis semula peraturan satu servis pada satu masa dan bukannya melakukan semuanya dalam satu malam yang berisiko.

Panduan ini mengandaikan persediaan Docker Compose berasaskan label daripada panduan reverse proxy Traefik. Halaman tersebut adalah asli untuk v3; panduan ini adalah untuk pelayan yang masih menjalankan tag traefik:v2.

Penamaan semula dan penyingkiran

• ipWhiteList kini menjadi ipAllowList, untuk middleware HTTP mahupun TCP. Pilihan di dalamnya tidak berubah, jadi sourcerange mengekalkan maksud asalnya. Keluaran v3 semasa, termasuk v3.5, masih menerima nama lama sebagai alias yang ditamatkan (deprecated) dan terus menguatkuasakan senarai tersebut, jadi penamaan semula ini tidak akan menyebabkan kegagalan sistem. Walau bagaimanapun, lakukan penamaan semula: alias tersebut dijadualkan untuk dibuang dan ia akan hilang daripada senarai penamatan secara senyap tanpa notis.
• providers.docker.swarmMode=true telah dibuang. Swarm kini mempunyai penyedianya sendiri yang dikonfigurasikan sebagai providers.swarm.endpoint.
• Bahagian pilot telah dibuang sepenuhnya.
• experimental.http3 telah dibuang. HTTP/3 kini didayakan terus pada entrypoint.
• tls.caOptional telah dibuang daripada penyedia dan daripada middleware forwardAuth. Jika middleware tersebut berada di hadapan Authentik SSO yang dihoskan sendiri, memadamkan baris caOptional adalah satu-satunya langkah migrasi yang diperlukan, kerana alamat forwardAuth, header yang dipercayai, dan outpost di belakangnya semuanya berfungsi sama seperti pada v3.
• Penyedia metrik InfluxDB v1, penyedia Rancher, dan penyedia Marathon telah dibuang.
• Tracing telah beralih kepada OpenTelemetry. Backend tracing khusus, termasuk integrasi Jaeger dan Zipkin, telah dibuang, dan v3 kini mengeksport OTLP (protokol OpenTelemetry) sebagai gantinya.
• Pilihan ssl* yang ditamatkan di dalam middleware headers (sslRedirect, sslHost, dan selebihnya) telah dibuang. Pengalihan hala (redirection) entrypoint dan middleware redirectScheme telah menggantikannya.

Penyingkiran ini lebih penting daripada yang disangka, kerana Traefik enggan bermula apabila konfigurasi statiknya mengandungi pilihan yang tidak dikenali. Baris pilot atau swarmMode yang tertinggal akan menghentikan kontena semasa but dengan mesej incompatible deprecated static option found yang menamakan pilihan tersebut; pilihan yang tidak pernah dikenali oleh Traefik (ralat taip, atau tls.caOptional) akan menghentikannya dengan field not found sebagai gantinya. Bersihkan konfigurasi statik sebelum anda menukar tag imej.

Nama middleware yang benar-benar tidak dikenali oleh Traefik (ralat taip, atau nama yang telah dibuang dan bukannya dijadikan alias) akan gagal dengan cara berbeza: router yang merujuknya dimuatkan dengan ralat dan bukannya laluan, papan pemuka (dashboard) akan menandakannya, dan API akan melaporkan middleware "offce@docker" does not exist. Permintaan ke hostname tersebut akan menerima 404 kerana router tidak berjaya dimuatkan. Perlu diingat bahawa ipwhitelist TIDAK termasuk dalam kategori ini pada v3 semasa: ia kekal sebagai alias yang ditamatkan, jadi label yang tidak dinamakan semula akan terus berfungsi tanpa gangguan.

Sintaks peraturan berubah

Peraturan ialah tempat penulisan semula sebenar boleh berlaku. Perubahan dalam v3:

• Tanda backtick diperlukan di sekeliling nilai di dalam matcher. v2 turut menerima tanda petikan berkembar; v3 tidak menerimanya, jadi Host("app.example.com") mesti ditukar kepada Host(app.example.com).
• PathPrefix tidak lagi memahami ungkapan nalar (regular expressions) atau placeholder gaya {id}. Peraturan v2 seperti PathPrefix(/api/{version:v[0-9]+}) mesti ditukar kepada matcher PathRegexp yang ditulis dalam sintaks ungkapan nalar 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). Pengecualiannya ialah Header, HeaderRegexp, Query, dan QueryRegexp, yang masih menerima nama berserta nilai.
• Headers dan HeadersRegexp dinamakan semula kepada Header dan HeaderRegexp.
• HostHeader telah dibuang. Gunakan Host, yang memadankan perkara yang sama dalam v3.
• Dua matcher baharu diperkenalkan: QueryRegexp, dan ClientIP untuk memadankan alamat klien di dalam sesuatu peraturan.

Berita baiknya: peraturan Host(app.example.com) ringkas yang ditulis dengan backtick sudah pun menjadi sintaks v3 yang sah. Kebanyakan persediaan Compose kecil menggunakan tepat seperti itu, yang bermaksud kebanyakan label boleh dimigrasikan tanpa sebarang suntingan peraturan.

Audit label anda sebelum bermula

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

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

Setiap hasil carian adalah satu baris yang perlu disunting. ipwhitelist menjadi ipallowlist. HostHeader menjadi Host. Headers menjadi Header. Penanda tempat {...} di dalam PathPrefix menjadi pemadan PathRegexp. Koma di dalam Host() menjadi dua pemadan Host() yang digabungkan dengan ||. Sifar hasil carian bermakna label anda sudah menggunakan sintaks v3 yang sah, dan migrasi hanya tertumpu kepada konfigurasi statik serta tag imej. Skrin yang penuh dengan hasil carian juga merupakan masa yang sesuai untuk menilai sama ada ini masih proksi yang tepat untuk pelayan anda, dan perbandingan Traefik dengan Nginx dan Caddy meletakkan kos penulisan semula tersebut berbanding dengan keperluan yang diminta oleh dua perisian lain bagi setiap aplikasi.

Perkara yang kekal sama

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

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

Laluan migrasi

Langkah 1: kunci versi yang anda jalankan hari ini. Tukar sebarang tag traefik:latest atau traefik:v2 kepada keluaran tepat yang anda gunakan, contohnya traefik:v2.11, dan lakukan commit pada keseluruhan direktori compose ke git. Setiap langkah seterusnya boleh diterbalikkan dengan checkout. Jika mencipta semula satu servis dengan docker compose up -d <service> belum menjadi kebiasaan, panduan asas Docker Compose merangkumi operasi yang menjadi sandaran migrasi ini.

Langkah 2: bersihkan konfigurasi statik dan hidupkan mod keserasian. Buang setiap pilihan yang digugurkan dalam 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 command: compose: --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 gunakan perubahan tersebut lagi, kerana nama baharu itu belum wujud dalam v2. Edit ini dihantar bersama-sama dengan pertukaran pada langkah seterusnya. (Jika ada yang terlepas, v3 semasa masih mengiktiraf nama lama sebagai alias yang ditamatkan, jadi senarai tersebut terus dikuatkuasakan; betulkan pada pusingan seterusnya dan bukannya pada pukul 2 pagi.)

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

docker compose up -d
docker compose logs -f traefik

Oleh kerana mod keserasian dihidupkan, peraturan v2 anda terus sepadan, dan kerana up -d juga mencipta semula servis yang label middleware-nya telah anda namakan semula, router tersebut akan muncul dengan bersih. Log yang sihat tidak mempunyai baris field not found dan tiada baris does not exist.

Jujurlah dengan diri sendiri tentang tempoh masa yang dibuka oleh langkah ini. Router yang merujuk kepada nama middleware yang tidak dikenali oleh v3 (ralat taip, atau pilihan yang dibuang) akan tergendala dari saat Traefik baharu bermula sehingga bekas aplikasinya dicipta semula, yang pada satu mesin hanyalah beberapa saat yang diperlukan oleh docker compose up -d untuk memproses senarai tersebut. Jika sesuatu laluan benar-benar tidak boleh terputus, buang middleware yang dinamakan semula daripada label middlewares router tersebut sebelum pertukaran dan tambahkannya semula selepas itu, serta tentukan lebih awal sama ada laluan tersebut boleh berfungsi tanpa senarai kebenaran IP-nya untuk seminit di antaranya.

Langkah 5: migrasikan peraturan servis demi servis. Selesaikan satu aplikasi pada satu masa: tulis semula peraturannya kepada sintaks v3, cipta semula hanya servis tersebut dengan docker compose up -d app, dan uji sebelum meneruskan. Jika satu servis mempunyai peraturan yang anda belum boleh tulis semula, berikan router tunggal itu label jalan keluar traefik.http.routers.app.ruleSyntax=v2 dan teruskan.

Langkah 6: matikan mod keserasian. Apabila setiap peraturan menggunakan sintaks v3, padam defaultRuleSyntax dan sebarang label ruleSyntax, mulakan semula Traefik, dan sahkan setiap router masih menunjukkan status hijau dalam papan pemuka. Jangan selesa dengan mod keserasian yang dihidupkan: Traefik telah menamatkan kedua-dua pilihan tersebut dalam v3.4 dan akan membuangnya dalam versi utama seterusnya, jadi ia hanyalah jambatan, bukan destinasi.

Sebelum dan selepas: label satu servis

Berikut adalah satu aplikasi yang membawa setiap perubahan penting secara serentak: Host berbilang nilai, pemegang tempat 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 dimigrasikan 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 memecahkan Host berbilang nilai kepada dua pemadan (matcher) yang digabungkan dengan || dan menukar pemegang tempat tersebut kepada PathRegexp, manakala label middleware menukar ipwhitelist kepada ipallowlist. Entrypoint, penyelesai sijil (certificate resolver), sambungan router-ke-middleware, dan port servis tidak berubah.

Uji setiap servis dengan papan pemuka

Selepas setiap perubahan, buka halaman HTTP routers pada papan pemuka. Setiap router sepatutnya berwarna hijau. Router yang mempunyai lencana ralat akan menyatakan masalah tepatnya, yang biasanya berpunca daripada middleware yang tidak wujud di bawah nama baharunya atau peraturan yang tidak dapat dihuraikan oleh v3. Kemudian, sahkan dari luar, satu hostname pada satu masa:

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

200 atau ubah hala biasa aplikasi anda bermakna penghalaan dan TLS kedua-duanya berfungsi. 404 daripada Traefik bermakna router tidak berjaya dimulakan; kembali ke papan pemuka dan baca ralatnya. Pastikan docker compose logs -f traefik dibuka dalam terminal kedua semasa anda bekerja, kerana setiap kegagalan penghuraian akan dipaparkan di sana sebaik sahaja kontena dimulakan semula.

Integriti rollback

Simpan fail compose v2, konfigurasi statiknya, dan sandaran acme.json sehingga setiap servis dihalakan pada v3 dan telah diuji sepenuhnya. Melakukan rollback bermaksud menyemak keluar (checkout) komit pra-migrasi dan menjalankan docker compose up -d. Ia mestilah melibatkan keseluruhan fail, bukan sekadar tag imej, kerana label khusus v3 adalah salah di bawah v2 sama seperti label v2 yang salah di bawah v3: ipallowlist tidak wujud dalam v2, dan pemadanan PathRegexp juga tidak akan dihuraikan di sana. Jika acme.json hilang atau rosak semasa proses tersebut, pulihkan salinan sandaran sebelum memulakan v2, supaya proses rollback tidak menghabiskan had kadar Let's Encrypt anda dengan mengeluarkan lima sijil sekaligus.

FAQ

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

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

Apa yang berlaku kepada ipWhiteList dalam Traefik v3?

Ia telah dinamakan semula 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. Keluaran v3 semasa, termasuk v3.5, masih menerima nama lama sebagai alias yang telah ditamatkan (deprecated), jadi label yang tidak dinamakan semula masih akan menguatkuasakan senarai kebenaran (allowlist) secara senyap. Anggap ini sebagai tempoh pinjaman dan bukannya alasan untuk melangkau penamaan semula: alias tersebut dijadualkan untuk dibuang, dan nama middleware yang tidak dikenali oleh Traefik akan menyebabkan kegagalan dengan ralat router dan 404. Papan pemuka (dashboard) akan memaparkan ralat tersebut, dan permintaan ke hostname itu akan mengembalikan 404.

Adakah Traefik v3 masih boleh 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 bagi setiap router untuk baki konfigurasi individu selepas anda menukar tetapan lalai kembali. Anggap kedua-duanya sebagai sementara: Traefik telah menamatkan sokongan (deprecated) untuknya dalam v3.4 dan akan membuangnya dalam versi utama yang seterusnya.

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

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

Mengapa Traefik v3 gagal bermula selepas naik taraf?

Hampir selalu disebabkan oleh konfigurasi statik yang masih mengandungi pilihan yang telah dibuang dalam v3, dan Traefik enggan bermula jika terdapat pilihan yang tidak dikenali. Bagi saki-baki konfigurasi yang diketahui (pilot, providers.docker.swarmMode, experimental.http3), log akan menyatakan incompatible deprecated static option found dan menamakan punca ralat; bagi 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.