Migrasi Traefik v2 ke v3: Apa yang Rusak?

Perubahan antara Traefik v2 dan v3

Migrasi dari Traefik v2 ke v3 sebagian besar merupakan pekerjaan 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 diubah namanya atau dihapus. Beberapa provider dan opsi juga dihapus sepenuhnya. Komponen lainnya tetap berfungsi, termasuk entrypoints, konfigurasi sertifikat ACME, alur kerja Docker labels, dan acme.json Anda. v3 juga menyediakan mode kompatibilitas yang mempertahankan dukungan untuk sintaks aturan v2. Dengan demikian, Anda dapat meng-upgrade binary terlebih dahulu lalu menulis ulang aturan satu service pada satu waktu, bukan mengubah semuanya dalam satu malam yang berisiko.

Panduan ini mengasumsikan 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.7, masih menerima nama lama sebagai alias yang sudah deprecated dan tetap menerapkan daftar tersebut, sekaligus mencatat peringatan deprecated untuknya. Jadi, penggantian nama ini tidak menyebabkan layanan berhenti saat konfigurasi diterapkan. Tetap ganti namanya. Nama lama sudah deprecated, dan v2.11 sudah memahami ipAllowList, sehingga penggantian nama dapat diterapkan sebelum upgrade.
• providers.docker.swarmMode=true sudah dihapus. Swarm memiliki provider sendiri yang dikonfigurasi sebagai providers.swarm.endpoint.
• Bagian pilot sudah dihapus sepenuhnya.
• experimental.http3 sudah dihapus. HTTP/3 diaktifkan langsung pada entrypoint.
• tls.caOptional sudah dihapus dari provider dan middleware forwardAuth. Jika middleware tersebut berada di depan SSO Authentik yang di-host sendiri, menghapus baris caOptional sudah mencakup seluruh migrasinya. Alamat forwardAuth, header tepercaya, dan outpost di baliknya semuanya berperilaku sama pada v3.
• Metrics provider InfluxDB v1, provider Rancher, dan provider Marathon sudah dihapus.
• Tracing dipindahkan ke OpenTelemetry. Backend tracing khusus, termasuk integrasi Jaeger dan Zipkin, sudah dihapus. Sebagai gantinya, v3 mengekspor OTLP (protokol OpenTelemetry).
• Opsi ssl* yang sudah deprecated di dalam middleware headers (sslRedirect, sslHost, dan lainnya) sudah dihapus. Pengalihan pada entrypoint dan middleware redirectScheme menggantikannya.

Penghapusan ini lebih penting daripada yang terlihat karena Traefik tidak mau start jika konfigurasi statisnya berisi opsi yang sudah dihapus atau tidak dikenalnya. Baris pilot, swarmMode, experimental.http3, atau provider tls.caOptional yang tersisa akan menghentikan container saat boot. Traefik terlebih dahulu mencatat baris yang menyebutkan opsi tersisa tersebut, misalnya, opsi tls.CAOptional pada Docker provider sudah dihapus pada v3, lalu gagal dengan incompatible deprecated install configuration option found. Rilis hingga v3.4 menuliskan pesan terakhir tersebut sebagai incompatible deprecated static option found. Opsi yang sama sekali tidak dikenali Traefik, seperti salah ketik, akan menghentikannya dengan field not found dan node juga berhenti. Bersihkan konfigurasi statis sebelum mengubah image tag.

Nama middleware yang benar-benar tidak dikenali Traefik, baik karena salah ketik maupun karena namanya dihapus tanpa alias, gagal dengan cara berbeda. Router yang merujuknya dimuat dengan error, bukan sebagai route. Dashboard menandainya, dan API melaporkan middleware "offce@docker" does not exist. Request ke hostname tersebut mendapatkan 404 karena router tidak pernah aktif. Perhatikan bahwa ipwhitelist TIDAK termasuk dalam kategori ini pada v3 saat ini. Nama tersebut masih tersedia sebagai alias yang sudah deprecated, sehingga label yang belum diganti namanya tetap berfungsi tanpa gangguan.

Sintaks aturan berubah

Aturan adalah bagian yang memungkinkan penulisan ulang dilakukan. Berikut perubahan pada v3:

• Penggunaan tanda kutip bukan salah satunya. Kedua versi menerima nilai aturan dalam backtick atau tanda kutip ganda yang di-escape, serta menolak tanda kutip tunggal. Jadi, Host(app.example.com) dan Host("app.example.com") dengan tanda kutip ganda yang di-escape tetap valid tanpa perubahan.
• 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 sekarang 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 dan 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: PathRegexp dan QueryRegexp. ClientIP, yang digunakan untuk mencocokkan alamat client di dalam aturan, sudah tersedia sejak v2.11 dan tetap digunakan tanpa perubahan.

Kabar baiknya, aturan Host(app.example.com) sederhana yang ditulis menggunakan backtick sudah valid dalam sintaks v3. Sebagian besar setup Compose kecil menggunakan bentuk ini. 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 digunakan saat ini. Ubah setiap tag traefik:latest atau traefik:v2 menjadi rilis yang benar-benar sedang digunakan, misalnya traefik:v2.11, lalu commit seluruh direktori compose ke git. Setiap langkah berikutnya dapat dibatalkan dengan checkout. Jika Anda belum terbiasa membuat ulang satu service dengan docker compose up -d <service>, panduan dasar Docker Compose menjelaskan operasi yang diperlukan 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 agar secara default memperlakukan aturan sebagai sintaks v2. Di 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: terapkan penggantian nama middleware saat masih menggunakan v2.11. Cari nama lama dalam file compose Anda: grep -rn ipwhitelist docker-compose*.yml. Ubah setiap label ipwhitelist menjadi ipallowlist, lalu buat ulang service tersebut dengan docker compose up -d. v2.11 sudah menyediakan middleware IPAllowList, sehingga label yang telah diganti namanya dapat digunakan sebelum peralihan, dan peringatan penghentian penggunaan IPWhiteList tidak lagi muncul dalam log v2 Anda. Rilis sebelum v2.11 tidak mengenali nama baru. Jadi, jika pada langkah 1 Anda menetapkan v2 yang lebih lama, tingkatkan versinya ke traefik:v2.11 terlebih dahulu. (Jika ada yang terlewat, v3 saat ini masih menerima nama lama sebagai alias yang tidak lagi direkomendasikan, sehingga daftar tersebut tetap diterapkan. Perbaiki pada pemeriksaan berikutnya, bukan pada pukul 2 pagi.)

Langkah 4: ubah tag image. Tetapkan image Traefik ke rilis v3 saat ini, yaitu traefik:v3.7 per 11 October 2026 (v3.7.14 adalah patch terbaru), lalu:

docker compose up -d
docker compose logs -f traefik

Karena mode kompatibilitas aktif, aturan v2 Anda tetap cocok. Karena penggantian nama middleware sudah diterapkan pada v2.11, router tersebut dapat berjalan tanpa error konfigurasi. Log yang sehat tidak memiliki baris field not found maupun baris does not exist.

Bersikaplah realistis terhadap periode gangguan yang dapat terjadi pada langkah ini. Router yang merujuk nama middleware yang benar-benar tidak dikenali v3, misalnya karena typo atau opsi yang telah dihapus, tidak dapat digunakan sejak Traefik baru mulai berjalan hingga Anda memperbaiki labelnya dan membuat ulang container aplikasinya. Jika suatu route benar-benar tidak boleh mengalami gangguan, hapus middleware yang dicurigai dari label middlewares router tersebut sebelum peralihan. Tambahkan kembali setelahnya. Tentukan sebelumnya apakah route tersebut dapat berjalan tanpa middleware itu selama satu menit tersebut.

Langkah 5: migrasikan aturan satu per satu berdasarkan service. Kerjakan satu aplikasi setiap kali. Tulis ulang aturannya menggunakan sintaks v3, buat ulang hanya service tersebut dengan docker compose up -d app, lalu uji sebelum melanjutkan. Jika suatu service memiliki aturan yang belum dapat Anda tulis ulang, tambahkan label jalur pengecualian traefik.http.routers.app.ruleSyntax=v2 hanya 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 semua router tetap berstatus hijau pada dashboard. Jangan terus menggunakan mode kompatibilitas: Traefik menyatakan kedua opsi tersebut tidak lagi direkomendasikan pada v3.4 dan akan menghapusnya pada versi mayor berikutnya. Mode ini adalah 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 saat melakukan rollback

Simpan file compose v2, konfigurasi statisnya, dan backup acme.json sampai semua service merutekan trafik melalui v3 dan telah diuji dalam kondisi nyata. Rollback berarti melakukan checkout ke commit sebelum migrasi lalu menjalankan docker compose up -d. File yang digunakan harus merupakan file lengkap, bukan hanya tag image, karena sintaks khusus v3 tidak valid pada v2, sama seperti sintaks v2 tidak valid pada v3: matcher PathRegexp tidak akan dapat diparse di sana. Label ipallowlist yang telah diganti namanya dapat digunakan pada v2.11, tetapi tidak pada rilis v2 yang lebih lama karena rilis tersebut tidak mengenali nama baru itu. Jika acme.json hilang atau rusak selama proses, pulihkan salinan backup sebelum menjalankan v2 agar rollback tidak menghabiskan rate limit Let's Encrypt dengan 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 setup 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(), atau matcher Headers, HeadersRegexp, dan HostHeader yang sudah 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. v2.11 sudah menerima nama baru tersebut, sehingga Anda dapat mengganti nama sebelum melakukan upgrade. Rilis v3 saat ini, termasuk v3.7, masih menerima nama lama sebagai alias yang sudah deprecated. Jadi, label yang belum diubah namanya tetap menerapkan allowlist, tetapi hanya menghasilkan peringatan di log. Anggap ini sebagai waktu tambahan, bukan alasan untuk melewatkan penggantian nama. Nama deprecated dapat dihapus oleh suatu rilis. Sebaliknya, jika Traefik benar-benar tidak mengenali nama middleware, proses gagal dengan jelas melalui 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 mempertahankan sintaks v2 sebagai default selama proses migrasi. Gunakan label ruleSyntax=v2 per-router untuk konfigurasi yang masih menggunakan sintaks lama setelah Anda mengembalikan default ke v3. Anggap keduanya sebagai konfigurasi sementara. Traefik mendeprecasi keduanya pada v3.4 dan menghapusnya pada major version berikutnya.

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

Ya. Traefik v3 tetap membaca file acme.json yang ditulis oleh v2, sehingga sertifikat tidak diterbitkan ulang hanya karena binary berubah. Namun, 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 oleh v3. Traefik menolak start jika menemukan opsi yang tidak dikenali. Untuk opsi lama yang umum (pilot, providers.docker.swarmMode, experimental.http3, dan tls.caOptional milik provider), log menyebutkan penyebabnya, lalu menampilkan incompatible deprecated install configuration option found (incompatible deprecated static option found pada v3.4 dan versi sebelumnya). Untuk apa pun yang belum pernah dikenali oleh v3, seperti typo, log menampilkan field not found beserta node terkait. Hapus atau ganti setiap opsi tersebut, lalu start kembali container.