Migrasi Traefik v2 ke v3: Apa yang Rusak?

Perubahan antara Traefik v2 dan v3

Migrasi dari Traefik v2 ke v3 pada dasarnya hanya memerlukan penggantian nama. Perubahan nama yang paling dikenal adalah middleware ipWhiteList menjadi ipAllowList. Selain itu, v3 memperketat sintaks aturan router. PathPrefix tidak lagi memiliki fitur regex, dan beberapa matcher diganti nama atau dihapus. Beberapa provider dan opsi juga dihapus sepenuhnya. Komponen lainnya tetap berfungsi, termasuk entrypoint, konfigurasi sertifikat ACME, alur kerja label Docker, dan acme.json Anda. v3 juga menyediakan mode kompatibilitas yang tetap mendukung sintaks aturan v2. Dengan demikian, Anda dapat memperbarui binary terlebih dahulu lalu menulis ulang aturan satu service pada satu waktu, bukan mengubah semuanya dalam satu sesi yang berisiko.

Panduan ini mengasumsikan penggunaan setup Docker Compose berbasis label dari panduan reverse proxy Traefik. Halaman tersebut menggunakan v3 secara native. Panduan ini ditujukan untuk server yang masih menjalankan tag traefik:v2.

Penggantian nama dan penghapusan

• ipWhiteList kini menjadi ipAllowList, baik untuk middleware HTTP maupun TCP. Opsi di dalamnya tidak berubah, sehingga sourcerange tetap memiliki arti yang sama persis. Rilis v3 saat ini, termasuk v3.5, masih menerima nama lama sebagai alias yang sudah deprecated dan tetap menerapkan daftar tersebut. Jadi, penggantian nama ini tidak mematikan layanan saat konfigurasi diterapkan. Tetap ganti namanya: alias tersebut dijadwalkan untuk dihapus, dan nantinya hilang dari daftar deprecated tanpa pemberitahuan khusus.
• providers.docker.swarmMode=true telah dihapus. Swarm memiliki provider sendiri yang dikonfigurasi sebagai providers.swarm.endpoint.
• Bagian pilot telah dihapus sepenuhnya.
• experimental.http3 telah dihapus. HTTP/3 diaktifkan langsung pada entrypoint.
• tls.caOptional telah dihapus dari provider dan middleware forwardAuth. Jika middleware tersebut berada di depan Authentik SSO yang di-host sendiri, menghapus baris caOptional sudah merupakan seluruh proses migrasinya, karena alamat forwardAuth, header tepercaya, dan outpost di belakangnya tetap berperilaku sama pada v3.
• Provider metrik InfluxDB v1, provider Rancher, dan provider Marathon telah dihapus.
• Tracing dipindahkan ke OpenTelemetry. Backend tracing khusus, termasuk integrasi Jaeger dan Zipkin, telah dihapus, dan v3 menggunakan OTLP (protokol OpenTelemetry) sebagai gantinya.
• Opsi ssl* yang sudah deprecated di dalam middleware headers (sslRedirect, sslHost, dan opsi lainnya) telah dihapus. Pengalihan pada entrypoint dan middleware redirectScheme menggantikannya.

Penghapusan ini lebih penting daripada yang terlihat karena Traefik menolak untuk start jika konfigurasi statisnya berisi opsi yang tidak dikenalnya. Baris pilot atau swarmMode yang tersisa menghentikan container saat boot dengan pesan incompatible deprecated static option found yang menyebutkan opsi tersebut. Opsi yang memang tidak pernah dikenal Traefik, misalnya salah ketik atau tls.caOptional, menghentikannya dengan pesan field not found. Bersihkan konfigurasi statis sebelum mengubah image tag.

Nama middleware yang benar-benar tidak dikenal Traefik, misalnya karena salah ketik atau karena telah dihapus dan tidak hanya diberi alias, menyebabkan kegagalan yang berbeda. Router yang merujuk middleware tersebut dimuat dengan error, bukan sebagai route. Dashboard menandainya, dan API melaporkan middleware "offce@docker" does not exist. Permintaan ke hostname tersebut menghasilkan 404 karena router tidak pernah aktif. Perhatikan bahwa ipwhitelist TIDAK termasuk dalam kategori ini pada v3 saat ini: nama tersebut tetap tersedia sebagai alias yang sudah deprecated, sehingga label yang belum diganti namanya masih berfungsi tanpa gangguan.

Sintaks aturan berubah

Aturan adalah bagian yang memungkinkan penulisan ulang yang sebenarnya. Perubahan pada v3:

• Backtick wajib digunakan di sekitar nilai dalam matcher. v2 juga menerima tanda kutip ganda, tetapi v3 tidak. Jadi, Host("app.example.com") harus diubah menjadi Host(app.example.com).
• PathPrefix tidak lagi memahami regular expression atau placeholder bergaya {id}. Aturan v2 seperti PathPrefix(/api/{version:v[0-9]+}) harus diubah menjadi matcher PathRegexp yang ditulis menggunakan sintaks regular expression Go.
• Matcher kini hanya menerima satu nilai. v2 mengizinkan Host(app.example.com,www.example.com); v3 mengharuskan Host(app.example.com) || Host(www.example.com). Pengecualiannya adalah Header, HeaderRegexp, Query, dan QueryRegexp, yang tetap menerima nama serta nilai.
• Headers dan HeadersRegexp diubah namanya menjadi Header dan HeaderRegexp.
• HostHeader dihapus. Gunakan Host, yang mencocokkan hal yang sama pada v3.
• Dua matcher baru tersedia: QueryRegexp dan ClientIP untuk mencocokkan alamat klien di dalam aturan.

Kabar baiknya, aturan Host(app.example.com) sederhana yang ditulis menggunakan backtick sudah valid dalam sintaks v3. Sebagian besar setup Compose sederhana menggunakan format tersebut. Artinya, sebagian besar label dapat dimigrasikan tanpa mengubah aturan.

Audit label Anda sebelum memulai

Anda dapat mengukur skala migrasi dengan satu pencarian, karena setiap perubahan label yang menyebabkan kerusakan meninggalkan pola yang dapat ditemukan oleh grep:

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

Setiap hasil adalah satu baris yang perlu diedit. ipwhitelist menjadi ipallowlist. HostHeader menjadi Host. Headers menjadi Header. Placeholder {...} di dalam PathPrefix menjadi matcher PathRegexp. Koma di dalam Host() menjadi dua matcher Host() yang digabungkan dengan ||. Tidak ada hasil berarti label Anda sudah menggunakan sintaks v3 yang valid, sehingga migrasi cukup mencakup konfigurasi statis dan tag image. Jika hasilnya memenuhi satu layar, ini juga saat yang tepat untuk menilai apakah proxy ini masih sesuai untuk server tersebut. perbandingan Traefik dengan Nginx dan Caddy membantu membandingkan biaya penulisan ulang ini dengan konfigurasi yang diminta oleh dua proxy lainnya untuk setiap aplikasi.

Yang tetap sama

Entrypoint dan redirect HTTP-ke-HTTPS, ACME resolver dengan kedua jenis challenge, exposedByDefault, label router dan service, loadbalancer.server.port, serta dashboard semuanya berfungsi di v3 seperti di v2. Sertifikat Anda juga tetap dapat digunakan karena v3 terus membaca acme.json yang ditulis oleh v2. Tetap buat cadangan file tersebut sebelum memulai, karena rollback yang kehilangan file itu akan langsung terkena batas laju duplikasi sertifikat Let's Encrypt:

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

Jalur migrasi

Langkah 1: tetapkan versi yang Anda jalankan saat ini. Ubah setiap tag traefik:latest atau traefik:v2 menjadi rilis yang tepat sesuai versi yang sedang digunakan, misalnya traefik:v2.11, lalu commit seluruh direktori compose ke git. Setiap langkah berikutnya dapat dibatalkan dengan checkout. Jika membuat ulang satu service menggunakan docker compose up -d <service> belum menjadi hal yang biasa bagi Anda, panduan dasar Docker Compose menjelaskan operasi yang digunakan dalam migrasi ini.

Langkah 2: bersihkan konfigurasi statis dan aktifkan mode kompatibilitas. Hapus setiap opsi yang dihapus pada v3 (pilot, swarmMode, tls.caOptional, experimental.http3), lalu beri tahu v3 untuk memperlakukan aturan sebagai sintaks v2 secara default. Dalam traefik.yml:

core:
  defaultRuleSyntax: v2

Atau gunakan flag dalam daftar compose command:: --core.defaultRuleSyntax=v2. Mode kompatibilitas hanya mencakup sintaks aturan. Mode ini tidak mengembalikan opsi yang telah dihapus dan tidak mengganti nama middleware secara otomatis.

Langkah 3: siapkan penggantian nama middleware. Cari nama lama dalam file compose Anda: grep -rn ipwhitelist docker-compose*.yml. Edit setiap label ipwhitelist menjadi ipallowlist, tetapi jangan terapkan perubahan tersebut dulu karena nama baru itu belum ada di v2. Perubahan ini harus diterapkan bersamaan dengan pengalihan pada langkah berikutnya. Jika ada yang terlewat, v3 saat ini masih menerima nama lama sebagai alias yang sudah deprecated, sehingga daftar tersebut tetap diberlakukan. Perbaiki pada pemeriksaan berikutnya, bukan pada pukul 2 pagi.

Langkah 4: ubah tag image. Atur image Traefik ke rilis v3 saat ini, yaitu traefik:v3.5 pada saat dokumentasi ini ditulis, lalu:

docker compose up -d
docker compose logs -f traefik

Karena mode kompatibilitas aktif, aturan v2 Anda tetap cocok. Selain itu, up -d juga membuat ulang service yang label middleware-nya Anda ganti, sehingga router tersebut aktif tanpa error. Log yang sehat tidak memiliki baris field not found dan tidak memiliki baris does not exist.

Pahami dengan jelas jeda layanan yang dibuka oleh langkah ini. Router yang merujuk nama middleware yang benar-benar tidak dikenali oleh v3—karena salah ketik atau opsi yang dihapus—akan berhenti sejak Traefik baru dimulai sampai container aplikasinya dibuat ulang. Pada satu server, proses ini biasanya hanya memerlukan beberapa detik saat docker compose up -d memproses seluruh daftar. Jika sebuah route benar-benar tidak boleh mengalami gangguan, hapus middleware yang namanya diubah dari label middlewares router tersebut sebelum pengalihan, lalu tambahkan kembali setelahnya. Tentukan sebelumnya apakah route tersebut dapat berjalan tanpa daftar IP yang diizinkan selama satu menit di antaranya.

Langkah 5: migrasikan aturan satu service demi satu service. Kerjakan satu aplikasi setiap kali: tulis ulang aturannya ke sintaks v3, buat ulang service tersebut saja menggunakan docker compose up -d app, lalu uji sebelum melanjutkan. Jika sebuah service memiliki aturan yang belum dapat Anda tulis ulang, tambahkan label pengecualian traefik.http.routers.app.ruleSyntax=v2 pada router tersebut dan lanjutkan.

Langkah 6: nonaktifkan mode kompatibilitas. Setelah semua aturan menggunakan sintaks v3, hapus defaultRuleSyntax dan label ruleSyntax apa pun, restart Traefik, lalu pastikan setiap router tetap berstatus hijau di dashboard. Jangan terus menggunakan mode kompatibilitas: Traefik menandai kedua opsi tersebut sebagai deprecated pada v3.4 dan akan menghapusnya pada versi major berikutnya. Mode ini hanya jembatan, bukan tujuan akhir.

Sebelum dan sesudah: label satu service

Berikut contoh satu aplikasi yang menerapkan semua perubahan utama sekaligus: Host multi-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 service yang sama setelah 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 berubah. Rule memisahkan Host multi-nilainya menjadi dua matcher yang digabungkan dengan ||, lalu mengganti placeholder dengan PathRegexp. Label middleware mengganti ipwhitelist dengan ipallowlist. Entrypoint, certificate resolver, wiring router ke middleware, dan port service tidak berubah.

Uji setiap service melalui dashboard

Setelah setiap perubahan, buka halaman HTTP routers di dashboard. Semua router harus berstatus hijau. Router dengan lencana error menunjukkan masalahnya secara spesifik. Biasanya penyebabnya adalah middleware yang tidak ada dengan nama barunya atau rule v3 yang tidak dapat diparse. Selanjutnya, lakukan konfirmasi dari luar, satu hostname setiap kali:

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

200 atau redirect normal dari aplikasi Anda berarti routing dan TLS tetap berfungsi. 404 dari Traefik berarti router tidak berhasil berjalan. Kembali ke dashboard, lalu baca error-nya. Biarkan docker compose logs -f traefik tetap terbuka di terminal kedua selama proses berlangsung, karena setiap kegagalan parsing langsung tercatat di sana saat container dimulai ulang.

Kejujuran rollback

Simpan file compose v2, konfigurasi statisnya, dan backup acme.json sampai setiap service merutekan trafik melalui v3 dan telah diuji dalam penggunaan nyata. Rollback berarti checkout commit sebelum migrasi lalu menjalankan docker compose up -d. Seluruh file harus digunakan, bukan hanya tag image, karena label khusus v3 tidak valid pada v2, sama seperti label v2 tidak valid pada v3: ipallowlist tidak ada pada v2, dan matcher PathRegexp juga tidak dapat diparse di sana. Jika acme.json hilang atau rusak selama proses, pulihkan salinan backup sebelum menjalankan v2 agar rollback tidak menghabiskan rate limit Let's Encrypt untuk menerbitkan ulang lima sertifikat sekaligus.

FAQ

Apakah saya harus menulis ulang setiap aturan router untuk Traefik v3?

Tidak. Aturan Host(app.example.com) biasa yang ditulis dengan backtick valid pada kedua versi, dan ini mencakup sebagian besar konfigurasi Compose. Penulisan ulang hanya diperlukan jika aturan menggunakan fitur khusus v2: regex atau placeholder di dalam Path dan PathPrefix, beberapa hostname di dalam satu Host(), tanda kutip sebagai pengganti backtick, atau matcher Headers, HeadersRegexp, dan HostHeader yang telah dihapus.

Apa yang terjadi pada ipWhiteList di Traefik v3?

Namanya diubah menjadi ipAllowList, sedangkan konfigurasi di dalamnya tetap sama. Jadi, label v2 seperti traefik.http.middlewares.office.ipwhitelist.sourcerange=10.0.0.0/24 menjadi baris yang sama dengan ipallowlist di dalamnya. Rilis v3 saat ini, termasuk v3.5, masih menerima nama lama sebagai alias yang sudah deprecated. Jadi, label yang belum diubah namanya tetap menerapkan allowlist tanpa menimbulkan pesan. Anggap ini sebagai waktu tambahan, bukan alasan untuk menunda perubahan nama. Alias tersebut dijadwalkan untuk dihapus. Sebaliknya, nama middleware yang benar-benar tidak dikenali Traefik akan gagal secara jelas dengan error router dan respons 404. Dashboard menampilkan error tersebut, dan request ke hostname itu mengembalikan 404.

Apakah Traefik v3 masih dapat membaca sintaks aturan v2?

Ya. Atur core.defaultRuleSyntax: v2 dalam konfigurasi statis untuk tetap menggunakan sintaks v2 sebagai default selama proses migrasi. Setelah default dikembalikan, gunakan label ruleSyntax=v2 per-router untuk router yang masih tersisa. Anggap keduanya sebagai pengaturan sementara. Traefik telah mendeprecasi keduanya pada v3.4 dan akan menghapusnya pada versi mayor berikutnya.

Apakah sertifikat Let's Encrypt saya tetap tersedia setelah upgrade?

Ya. Traefik v3 tetap membaca file acme.json yang ditulis oleh v2. Jadi, sertifikat tidak diterbitkan ulang hanya karena binary berubah. Meskipun demikian, salin file tersebut ke lokasi yang aman sebelum memulai. Rollback atau volume yang terhapus dan menyebabkan acme.json hilang akan memaksa penerbitan ulang semua sertifikat sekaligus. Let's Encrypt hanya mengizinkan lima sertifikat duplikat per minggu untuk kumpulan hostname yang sama.

Mengapa Traefik v3 gagal start setelah upgrade?

Hampir selalu karena konfigurasi statis masih berisi opsi yang dihapus pada v3. Traefik menolak start jika menemukan opsi yang tidak dikenalnya. Untuk opsi lama yang umum (pilot, providers.docker.swarmMode, experimental.http3), log menampilkan incompatible deprecated static option found dan menyebutkan penyebabnya. Untuk opsi yang tidak pernah dikenal v3, seperti tls.caOptional, log menampilkan field not found beserta node terkait. Hapus atau ganti setiap opsi tersebut, lalu start kembali container.