cara migrasi Traefik v2 ke v3

Perubahan antara Traefik v2 dan v3

Migrasi dari Traefik v2 ke v3 sebagian besar adalah proses penggantian nama. Perubahan yang paling utama adalah middleware ipWhiteList yang berubah menjadi ipAllowList. Selain itu, v3 memperketat sintaks aturan router (PathPrefix kehilangan fitur regex, beberapa matcher diubah namanya atau dihapus), menghapus beberapa provider dan opsi, namun tetap mempertahankan fungsi lainnya: entrypoints, pengaturan sertifikat ACME, alur kerja label Docker, dan acme.json Anda tetap berfungsi. v3 juga menyertakan mode kompatibilitas yang menjaga sintaks aturan v2 tetap berjalan. Hal ini memungkinkan Anda memperbarui binary terlebih dahulu dan menulis ulang aturan satu per satu untuk setiap layanan, alih-alih melakukannya sekaligus dalam satu waktu yang berisiko.

Panduan ini mengasumsikan penggunaan pengaturan Docker Compose berbasis label dari panduan reverse proxy Traefik. Halaman tersebut menggunakan v3 secara asli; halaman ini ditujukan untuk sistem yang masih menjalankan tag traefik:v2.

Perubahan nama dan penghapusan

• ipWhiteList sekarang menjadi ipAllowList, baik untuk middleware HTTP maupun TCP. Opsi di dalamnya tidak berubah, sehingga sourcerange tetap memiliki makna yang sama. Rilis v3 saat ini, termasuk v3.5, masih menerima nama lama sebagai alias yang usang (deprecated) dan tetap menerapkan daftar tersebut, sehingga perubahan nama ini tidak akan menghentikan sistem. Tetap lakukan perubahan nama: alias tersebut dijadwalkan untuk dihapus, dan akan hilang dari daftar deprecation secara diam-diam.
• providers.docker.swarmMode=true telah dihapus. Swarm kini memiliki provider sendiri, yang dikonfigurasi sebagai providers.swarm.endpoint.
• Bagian pilot telah dihapus sepenuhnya.
• experimental.http3 telah dihapus. HTTP/3 kini diaktifkan langsung pada entrypoint.
• tls.caOptional telah dihapus dari provider dan dari middleware forwardAuth.
• 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 kini mengekspor OTLP (OpenTelemetry protocol).
• Opsi ssl* yang usang di dalam middleware headers (sslRedirect, sslHost, dan lainnya) telah dihapus. Redireksi entrypoint dan middleware redirectScheme telah menggantikannya.

Penghapusan ini lebih penting daripada kelihatannya, karena Traefik akan menolak untuk berjalan jika konfigurasi statisnya mengandung opsi yang tidak dikenali. Baris pilot atau swarmMode yang tersisa akan menghentikan container saat booting dengan pesan incompatible deprecated static option found yang menyebutkan opsi tersebut; opsi yang benar-benar tidak dikenal oleh Traefik (kesalahan ketik, atau tls.caOptional) akan menghentikannya dengan pesan field not found. Bersihkan konfigurasi statis sebelum Anda mengubah tag image.

Nama middleware yang benar-benar tidak dikenal oleh Traefik (kesalahan ketik, atau nama yang dihapus alih-alih dijadikan alias) akan gagal dengan cara berbeda: router yang merujuk ke middleware tersebut akan memuat error alih-alih rute, dashboard akan menandainya, dan API akan melaporkan middleware "offce@docker" does not exist. Permintaan ke hostname tersebut akan menghasilkan 404 karena router tidak berhasil berjalan. Perlu dicatat bahwa ipwhitelist BUKAN termasuk dalam kategori ini pada v3 saat ini: ia tetap ada sebagai alias yang usang, sehingga label yang belum diubah namanya akan tetap berfungsi secara normal.

Perubahan sintaks aturan

Aturan adalah tempat terjadinya penulisan ulang yang signifikan. Perubahan pada v3:

• Backticks wajib digunakan untuk nilai di dalam matcher. v2 juga menerima tanda kutip ganda; v3 tidak, sehingga Host("app.example.com") harus diubah menjadi Host(app.example.com).
• PathPrefix tidak lagi memahami regular expression atau placeholder gaya {id}. Aturan v2 seperti PathPrefix(/api/{version:v[0-9]+}) harus diubah menjadi matcher PathRegexp yang ditulis dengan sintaks regular expression Go.
• Matcher sekarang hanya menerima satu nilai. v2 mengizinkan Host(app.example.com,www.example.com); v3 memerlukan Host(app.example.com) || Host(www.example.com). Pengecualiannya adalah Header, HeaderRegexp, Query, dan QueryRegexp, yang tetap menggunakan nama ditambah 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) biasa yang ditulis dengan backticks sudah merupakan sintaks v3 yang valid. Sebagian besar pengaturan Compose kecil menggunakan format tersebut, yang berarti sebagian besar label dapat bermigrasi tanpa perlu mengedit aturan.

Audit label Anda sebelum memulai

Anda dapat mengukur ukuran migrasi dengan satu pencarian, karena setiap perubahan label yang bersifat breaking meninggalkan pola yang dapat ditemukan oleh grep:

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

Setiap hasil temuan adalah satu baris yang harus diedit. ipwhitelist menjadi ipallowlist. HostHeader menjadi Host. Headers menjadi Header. Placeholder {...} di dalam PathPrefix menjadi matcher PathRegexp. Tanda koma di dalam Host() menjadi dua matcher Host() yang dihubungkan oleh ||. Jika tidak ada hasil temuan, berarti label Anda sudah menggunakan sintaks v3 yang valid, dan migrasi hanya terbatas pada konfigurasi statis ditambah tag image.

Apa yang tetap sama

Entrypoint dan pengalihan HTTP-ke-HTTPS, ACME resolver dengan kedua jenis tantangan, exposedByDefault, label router dan service, loadbalancer.server.port, serta dashboard tetap berfungsi di v3 seperti pada v2. Sertifikat Anda juga tetap tersedia karena v3 tetap membaca acme.json yang ditulis oleh v2. Tetap lakukan cadangan file tersebut sebelum memulai, karena proses rollback yang menyebabkan kehilangan file tersebut akan langsung terkena limitasi duplikasi sertifikat dari Let's Encrypt:

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

Jalur migrasi

Langkah 1: tetapkan versi yang Anda gunakan saat ini. Ubah setiap tag traefik:latest atau traefik:v2 ke versi spesifik yang Anda gunakan, misalnya traefik:v2.11, dan lakukan commit pada seluruh direktori compose ke git. Setiap langkah selanjutnya dapat dibatalkan dengan melakukan checkout. Jika membuat ulang satu layanan dengan docker compose up -d <service> belum Anda kuasai, panduan dasar Docker Compose membahas operasi yang digunakan dalam migrasi ini.

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

core:
  defaultRuleSyntax: v2

Atau sebagai flag dalam daftar compose command:: --core.defaultRuleSyntax=v2. Mode kompatibilitas hanya mencakup sintaks aturan. Mode ini tidak memulihkan opsi yang telah dihapus, dan tidak mengubah nama middleware untuk Anda.

Step 3: siapkan perubahan nama middleware. Cari nama lama di file compose Anda: grep -rn ipwhitelist docker-compose*.yml. Ubah setiap label ipwhitelist menjadi ipallowlist, tetapi jangan terapkan perubahan tersebut sekarang, karena nama baru tersebut belum ada di v2. Perubahan ini akan diterapkan bersamaan dengan langkah berikutnya. (Jika ada yang terlewat, v3 saat ini masih mengenali nama lama sebagai alias yang usang, sehingga daftar tetap berjalan; perbaiki pada putaran berikutnya daripada melakukannya pada jam 2 pagi.)

Langkah 4: ubah tag image. Atur image Traefik ke rilis v3 terbaru, traefik:v3.5 pada saat penulisan ini, lalu:

docker compose up -d
docker compose logs -f traefik

Karena mode kompatibilitas aktif, aturan v2 Anda tetap cocok, dan karena up -d juga membuat ulang layanan yang label middleware-nya telah Anda ubah namanya, router tersebut akan berjalan dengan normal. Log yang sehat tidak memiliki baris field not found dan tidak memiliki baris does not exist.

Pertimbangkan risiko dari jendela waktu yang dibuka oleh langkah ini. Router yang merujuk ke nama middleware yang tidak dikenal oleh v3 (kesalahan ketik, atau opsi yang dihapus) akan mati sejak Traefik baru dimulai hingga kontainer aplikasinya dibuat ulang, yang pada satu mesin hanya membutuhkan waktu beberapa detik docker compose up -d untuk memproses daftar tersebut. Jika sebuah rute benar-benar tidak boleh terputus, hapus middleware yang telah diubah namanya dari label middlewares router tersebut sebelum melakukan perubahan, lalu tambahkan kembali setelahnya, dan putuskan sebelumnya apakah rute tersebut dapat berjalan tanpa daftar izin IP-nya selama satu menit tersebut.

Langkah 5: migrasi aturan per layanan. Kerjakan satu aplikasi satu per satu: tulis ulang aturannya ke sintaks v3, buat ulang hanya layanan tersebut dengan docker compose up -d app, dan uji sebelum lanjut ke langkah berikutnya. Jika satu layanan memiliki aturan yang belum bisa Anda tulis ulang, berikan label darurat traefik.http.routers.app.ruleSyntax=v2 pada router tersebut dan lanjutkan prosesnya.

Langkah 6: matikan mode kompatibilitas. Setelah semua aturan menggunakan sintaks v3, hapus defaultRuleSyntax dan semua label ruleSyntax, restart Traefik, dan pastikan setiap router tetap berwarna hijau di dashboard. Jangan terus menggunakan mode kompatibilitas: Traefik telah menandai kedua opsi tersebut sebagai usang pada v3.4 dan akan menghapusnya pada versi mayor berikutnya, sehingga opsi ini hanyalah jembatan, bukan tujuan akhir.

Sebelum dan sesudah: label pada sebuah service

Berikut adalah satu aplikasi yang mengalami semua perubahan populer sekaligus: sebuah Host multi-value, sebuah placeholder PathPrefix, dan sebuah 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 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 berubah. Aturan tersebut memecah Host multi-value menjadi dua matcher yang dihubungkan oleh || dan mengganti placeholder dengan PathRegexp, sedangkan label middleware mengganti ipwhitelist dengan ipallowlist. Entrypoint, certificate resolver, sambungan router-ke-middleware, dan port service tidak berubah.

Uji setiap layanan dengan dashboard

Setelah setiap perubahan, buka halaman HTTP routers pada dashboard. Setiap router harus berwarna hijau. Router dengan lencana error akan menunjukkan masalah spesifiknya, biasanya karena middleware tidak ditemukan dengan nama baru atau aturan yang tidak dapat diproses oleh v3. Kemudian konfirmasi dari luar, satu per satu hostname:

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

200 atau pengalihan (redirect) normal aplikasi Anda berarti routing dan TLS berhasil. 404 dari Traefik berarti router gagal berjalan; kembali ke dashboard dan baca pesan errornya. Biarkan docker compose logs -f traefik tetap terbuka di terminal kedua selama Anda bekerja, karena setiap kegagalan parsing akan muncul di sana saat kontainer melakukan restart.

Kejujuran Rollback

Simpan file compose v2, konfigurasi statisnya, dan cadangan acme.json hingga setiap layanan telah menggunakan v3 dan telah diuji secara nyata. Melakukan rollback berarti melakukan checkout pada commit sebelum migrasi dan menjalankan docker compose up -d. Anda harus menggunakan seluruh file, bukan hanya tag image. Hal ini karena label khusus v3 akan menyebabkan kesalahan pada v2, sama seperti kesalahan label v2 pada v3: ipallowlist tidak ada di v2, dan matcher PathRegexp juga tidak akan dapat diproses di sana. Jika acme.json hilang atau rusak selama proses berlangsung, pulihkan salinan cadangan sebelum memulai v2. Hal ini dilakukan agar proses rollback tidak menghabiskan limit rate Let's Encrypt Anda untuk menerbitkan 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 backticks tetap valid di kedua versi, dan ini mencakup sebagian besar pengaturan 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(), penggunaan tanda kutip alih-alih backticks, atau matcher Headers, HeadersRegexp, dan HostHeader yang telah dihapus.

Apa yang terjadi dengan ipWhiteList di Traefik v3?

Nama tersebut telah diubah menjadi ipAllowList, dengan konfigurasi di dalamnya tetap sama, sehingga 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 telah usang (deprecated), sehingga label yang tidak diubah tetap menerapkan allowlist secara diam-diam. Anggap ini sebagai masa transisi, bukan alasan untuk melewatkan perubahan nama: alias tersebut dijadwalkan untuk dihapus, dan jika middleware yang tidak dikenal oleh Traefik digunakan, sistem akan memunculkan error router dan 404. Dashboard akan menampilkan error tersebut, dan permintaan ke hostname tersebut akan mengembalikan 404.

Apakah Traefik v3 masih bisa membaca sintaks aturan v2?

Ya. Atur core.defaultRuleSyntax: v2 pada konfigurasi statis untuk tetap menggunakan sintaks v2 sebagai default selama proses migrasi, dan gunakan label ruleSyntax=v2 per-router untuk sisa aturan lainnya setelah Anda mengembalikan default ke v3. Anggap keduanya sebagai solusi sementara: Traefik telah menandai keduanya sebagai deprecated pada v3.4 dan akan menghapusnya pada versi mayor berikutnya.

Apakah sertifikat Let's Encrypt saya akan tetap aman setelah upgrade?

Ya. Traefik v3 tetap membaca file acme.json yang ditulis oleh v2, sehingga sertifikat tidak akan diterbitkan ulang hanya karena perubahan binary. Tetap salin file tersebut ke tempat yang aman sebelum memulai, karena rollback atau volume yang terhapus yang menyebabkan hilangnya acme.json akan memaksa penerbitan ulang semua sertifikat secara bersamaan, dan Let's Encrypt hanya mengizinkan lima sertifikat duplikat per minggu untuk set hostname yang sama.

Mengapa Traefik v3 gagal dijalankan setelah upgrade?

Hampir selalu karena konfigurasi statis masih mengandung opsi yang telah dihapus pada v3, dan Traefik menolak untuk berjalan jika terdapat opsi yang tidak dikenali. Untuk sisa konfigurasi yang umum (pilot, providers.docker.swarmMode, experimental.http3), log akan menampilkan incompatible deprecated static option found dan menyebutkan penyebabnya; untuk hal lain yang tidak dikenal oleh v3, seperti tls.caOptional, log akan menampilkan field not found beserta nodenya. Hapus atau ganti setiap opsi tersebut, lalu jalankan kembali kontainer.