Next.js: Canary Deploy App Router dengan Rollback Cepat dan Alerting

Canary deploy untuk Next.js App Router adalah cara merilis versi baru ke sebagian kecil trafik lebih dulu, lalu menaikkan porsinya bertahap jika metrik tetap sehat. Pendekatan ini membantu mendeteksi regresi lebih cepat dibanding deploy penuh, sekaligus memberi jalur rollback cepat tanpa memutus layanan.

Pada aplikasi Next.js, canary deployment paling aman jika dikendalikan di level proxy atau platform ingress, bukan lewat logika aplikasi semata. Dengan begitu, Anda bisa membagi trafik antar dua rilis, memantau error rate dan latency, menjalankan smoke test setelah deploy, lalu menarik canary dari jalur trafik jika muncul lonjakan 5xx atau error pada API route.

Kapan canary deployment layak dipakai

Canary cocok saat Anda merilis perubahan yang berisiko memengaruhi perilaku runtime, misalnya:

perubahan route handler di App Router atau API route,
integrasi baru ke layanan eksternal,
refactor server-side rendering atau data fetching,
perubahan middleware, autentikasi, cache, atau konfigurasi environment.

Jika aplikasi masih kecil dan dampak rollback sangat rendah, strategi blue-green atau deploy biasa mungkin cukup. Namun begitu trafik mulai signifikan dan incident cost tinggi, canary memberi kontrol lebih baik.

Arsitektur singkat: traffic splitting di level proxy/platform

Prinsip dasarnya sederhana: jalankan dua versi aplikasi secara paralel.

Stable: versi yang saat ini melayani mayoritas pengguna.
Canary: versi baru yang menerima sebagian kecil trafik, misalnya 1%, 5%, lalu 10%.

Pembagian trafik sebaiknya dilakukan di level reverse proxy, ingress, load balancer, atau platform deploy. Alasannya:

rollback lebih cepat karena cukup mengubah bobot trafik,
tidak perlu menyisipkan logika pembagian trafik ke aplikasi,
lebih konsisten untuk request ke halaman dan API,
mudah diintegrasikan dengan observability dan health check.

Pola routing yang umum

Weighted traffic split: sebagian trafik dialihkan ke canary berdasarkan bobot.
Header atau cookie-based routing: berguna untuk internal QA atau smoke test terarah ke canary.
Session affinity: opsional jika Anda ingin pengguna tetap berada di versi yang sama selama satu sesi.

Untuk Next.js App Router, model ini biasanya lebih aman daripada mencoba mengatur pembagian trafik dari middleware aplikasi. Middleware cocok untuk eksperimen ringan, tetapi bukan alat utama untuk rollback infrastruktur.

Catatan penting untuk Next.js App Router

Pastikan kedua versi kompatibel terhadap dependensi eksternal yang sama, terutama:

skema database,
kontrak API internal,
format cache,
cookie atau session format,
environment variable.

Kesalahan umum pada canary bukan di traffic split, melainkan di backward compatibility. Jika canary menulis data dengan format baru yang tidak bisa dibaca versi stable, rollback bisa gagal secara fungsional meskipun infrastruktur sukses.

Prasyarat sebelum mengaktifkan canary

1. Build yang dapat direproduksi

Gunakan artefak build yang jelas dan bisa dilacak. Setiap rilis minimal punya:

commit SHA,
nomor build atau release ID,
waktu deploy,
catatan perubahan singkat.

Release ID ini sebaiknya dimasukkan ke log aplikasi agar Anda bisa membedakan error dari stable dan canary.

2. Health check yang sederhana tapi berguna

Jangan gunakan health check yang hanya mengembalikan 200 tanpa memverifikasi kesiapan dasar aplikasi. Untuk Next.js, endpoint health check sebaiknya memeriksa:

proses aplikasi hidup,
server dapat merespons request,
opsional: koneksi dasar ke dependency penting seperti database atau cache.

Jangan membuat health check terlalu berat. Tujuannya adalah mendeteksi kondisi tidak sehat dengan cepat, bukan meniru seluruh alur bisnis.

// app/api/health/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  const startedAt = Date.now();

  try {
    // Tambahkan pengecekan ringan ke dependency penting bila perlu.
    // Hindari query berat atau memanggil terlalu banyak layanan.

    return NextResponse.json({
      status: 'ok',
      uptimeHint: 'ready',
      responseTimeMs: Date.now() - startedAt,
      release: process.env.RELEASE_ID || 'unknown'
    }, { status: 200 });
  } catch {
    return NextResponse.json({
      status: 'error',
      release: process.env.RELEASE_ID || 'unknown'
    }, { status: 503 });
  }
}

Jika Anda membedakan liveness dan readiness, gunakan endpoint readiness untuk menerima trafik, bukan sekadar liveness.

3. Logging terstruktur

Minimal sertakan field berikut di log server:

timestamp,
severity,
release ID,
route atau pathname,
status code,
latency,
request ID atau trace ID.

Tanpa release ID, Anda akan kesulitan membuktikan apakah lonjakan error hanya datang dari canary atau memang masalah sistemik.

Langkah implementasi canary deployment untuk Next.js App Router

1. Siapkan dua deployment aktif

Jalankan stable dan canary secara paralel. Keduanya harus menggunakan konfigurasi runtime yang sama sejauh mungkin, kecuali release ID atau flag tertentu yang memang disengaja.

Contoh variabel lingkungan yang berguna:

RELEASE_ID=2026-06-15.1
DEPLOY_SLOT=canary

Di level aplikasi, Anda dapat mencetak release ini pada log atau response header untuk membantu verifikasi.

2. Arahkan trafik internal terlebih dahulu

Sebelum memberi trafik pengguna umum, arahkan request dari QA atau tim on-call ke canary menggunakan header atau cookie khusus di level proxy. Tujuannya:

menjalankan smoke test pada rilis nyata,
memverifikasi route penting,
memastikan API route tidak gagal karena environment atau konfigurasi.

3. Jalankan smoke test setelah deploy

Smoke test tidak perlu panjang, tetapi harus mewakili jalur yang paling kritikal. Untuk Next.js App Router, minimal uji:

halaman utama atau landing page,
halaman yang menggunakan server-side data fetching,
satu API route penting,
alur login jika autentikasi adalah bagian utama sistem,
halaman error atau fallback dasar jika relevan.

Contoh smoke test sederhana dengan shell:

#!/usr/bin/env sh
set -eu

BASE_URL="$1"

curl -fsS "$BASE_URL/" > /dev/null
curl -fsS "$BASE_URL/api/health" > /dev/null
curl -fsS "$BASE_URL/api/example" > /dev/null

echo "smoke test passed"

Gunakan endpoint yang benar-benar ada di aplikasi Anda. Jangan mengandalkan endpoint health saja, karena banyak bug justru muncul pada route bisnis.

4. Mulai dari porsi trafik kecil

Praktik umum adalah memulai dari trafik kecil, misalnya 1% atau 5%, lalu menunggu beberapa menit hingga metrik cukup stabil. Setelah itu, naikkan bertahap:

canary menerima trafik kecil,
amati error rate, latency, success rate, CPU, memory,
jika sehat, naikkan bobot,
jika tidak sehat, rollback dengan mengembalikan bobot ke stable 100%.

Tidak ada angka universal untuk durasi setiap tahap. Sesuaikan dengan volume trafik dan seberapa cepat masalah biasanya terlihat. Aplikasi dengan trafik rendah perlu waktu observasi lebih lama untuk menghasilkan sinyal yang bermakna.

Observability minimum yang wajib ada

Tujuan observability pada canary bukan mengumpulkan semua data, tetapi cukup untuk menjawab satu pertanyaan penting: apakah canary lebih buruk daripada stable?

Metrik minimum

Error rate: persentase request gagal, terutama 5xx.
Success rate: persentase request sukses, biasanya kebalikan dari error rate tetapi tetap berguna sebagai sinyal utama.
Latency: setidaknya p50 dan p95 atau p99 jika tersedia.
CPU: untuk mendeteksi lonjakan komputasi atau loop tak terduga.
Memory: untuk melihat kebocoran atau footprint yang memburuk setelah rilis.

Jika aplikasi sangat bergantung pada dependency eksternal, tambahkan metrik berikut:

error ke database atau cache,
timeout ke API upstream,
jumlah koneksi aktif atau antrean request.

Segmentasi metrik yang benar

Pastikan metrik bisa difilter minimal berdasarkan:

release ID,
deployment slot: stable atau canary,
route atau kelompok route,
status code.

Tanpa segmentasi ini, Anda mungkin melihat sistem “baik-baik saja” secara global, padahal canary sebenarnya rusak tetapi hanya melayani sebagian kecil trafik.

Alerting yang relevan

Alerting sebaiknya fokus pada gejala yang benar-benar perlu tindakan cepat. Untuk canary, alert yang umum dan masuk akal:

lonjakan 5xx pada canary di atas baseline stable,
error API route meningkat setelah deploy,
latency p95 canary memburuk signifikan dibanding stable,
health check canary gagal berulang,
CPU atau memory canary naik tajam dan mendekati batas runtime.

Hindari alert yang terlalu sensitif pada volume trafik rendah. Canary kecil memang rawan menghasilkan sinyal yang berisik. Lebih baik menggunakan ambang berbasis rasio dan membandingkan canary terhadap stable, bukan hanya angka absolut.

Contoh aturan alert secara umum

Jika 5xx canary naik konsisten selama beberapa interval pengamatan, kirim peringatan ke on-call.
Jika readiness check gagal berulang, hentikan kenaikan trafik dan evaluasi rollback.
Jika error route tertentu naik tajam setelah deploy, tandai sebagai regresi kandidat meskipun error global belum terlihat besar.

Format implementasi alert akan bergantung pada alat monitoring yang Anda pakai. Yang penting adalah logika deteksinya, bukan vendor tertentu.

Rollback tanpa downtime

Rollback tercepat dalam canary deployment biasanya bukan redeploy kode lama, melainkan mengalihkan seluruh trafik kembali ke stable. Karena stable masih aktif, pengguna tetap dilayani tanpa downtime.

Urutan rollback yang disarankan

bekukan kenaikan trafik ke canary,
ubah bobot traffic split menjadi 0% ke canary dan 100% ke stable,
verifikasi success rate dan latency kembali normal,
biarkan canary tetap hidup sementara untuk pengumpulan log jika perlu,
setelah bukti cukup, nonaktifkan canary atau buat deployment perbaikan.

Keuntungan pendekatan ini adalah kecepatan. Anda tidak menunggu pipeline build ulang saat insiden sedang berlangsung.

Hal yang perlu diperhatikan saat rollback

Perubahan skema database: gunakan migrasi yang kompatibel maju dan mundur. Hindari perubahan destruktif yang memaksa semua instance pindah serentak.
Cache: jika format cache berubah, gunakan versi key atau namespace berbeda.
Session/cookie: pastikan stable masih bisa membaca session dari canary jika rollback mungkin terjadi.
Background job: bila canary menghasilkan pekerjaan async dengan format baru, pastikan worker stable tetap kompatibel.

Runbook insiden: canary meningkatkan 5xx atau error API route

Runbook ini sengaja dibuat singkat agar bisa dipakai saat situasi nyata.

Trigger

alert 5xx canary aktif, atau
smoke test gagal pada API route, atau
latency canary melonjak dan diikuti timeout.

Langkah respons awal

Konfirmasi scope: apakah error hanya terjadi di canary atau juga di stable?
Cek health check: apakah endpoint readiness/health gagal?
Cek route terdampak: halaman tertentu, semua API route, atau hanya satu handler?
Bandingkan release ID: pastikan insiden memang terkait rilis baru.

Tindakan mitigasi

set bobot canary ke 0%,
pastikan stable menerima 100% trafik,
verifikasi penurunan error rate dan pemulihan latency,
umumkan status mitigasi ke channel insiden.

Investigasi cepat setelah mitigasi

periksa log 5xx berdasarkan release ID canary,
cek apakah ada environment variable yang hilang atau salah,
cek timeout ke database, cache, atau API upstream,
cek perubahan pada route handler, middleware, atau autentikasi,
cek konsumsi memory/CPU untuk tanda loop, payload besar, atau kebocoran.

Contoh gejala dan dugaan akar masalah

5xx hanya di API route tertentu: kemungkinan regresi validasi input, perubahan kontrak response, atau dependency upstream gagal.
Semua route lambat lalu timeout: kemungkinan bottleneck koneksi database, cache miss ekstrem, atau memory pressure.
Health check sehat tetapi route bisnis gagal: health check terlalu dangkal dan tidak mewakili dependency penting.

Kriteria menutup insiden

trafik 100% sudah kembali ke stable,
error rate kembali ke baseline normal,
tidak ada alert aktif terkait rilis,
hipotesis akar masalah terdokumentasi,
tindak lanjut perbaikan memiliki owner.

Contoh checklist rilis aman

build lulus dan artefak dapat dilacak,
migrasi database bersifat kompatibel,
health check readiness tersedia,
release ID masuk ke log dan metrik,
smoke test canary lulus,
alerting aktif sebelum trafik dinaikkan,
rollback plan sudah jelas dan bisa dilakukan tanpa redeploy.

Template postmortem ringkas

Postmortem tidak perlu panjang, tetapi harus cukup untuk mencegah pengulangan insiden.

Judul insiden:
Canary Next.js App Router meningkatkan 5xx pada API route /api/orders

Ringkasan:
Setelah canary menerima sebagian trafik, error 5xx meningkat pada satu API route.
Rollback dilakukan dengan mengalihkan trafik kembali ke stable tanpa downtime.

Dampak:
- Persentase trafik terdampak:
- Durasi insiden:
- Endpoint/fitur terdampak:
- Pengguna atau proses bisnis yang terpengaruh:

Timeline:
- Waktu deploy canary:
- Waktu alert pertama:
- Waktu mitigasi rollback:
- Waktu layanan kembali normal:

Akar masalah:
- Perubahan apa yang memicu error:
- Mengapa lolos dari pengujian sebelum deploy:

Deteksi:
- Alert apa yang aktif:
- Sinyal apa yang terlambat atau tidak ada:

Mitigasi:
- Langkah rollback yang dilakukan:
- Verifikasi setelah rollback:

Tindakan pencegahan:
- Tambah smoke test untuk route terkait
- Perbaiki health check atau observability
- Tambah validasi kompatibilitas dependency
- Revisi prosedur deploy/canary gate

Owner dan target waktu:
- Tugas 1:
- Tugas 2:
- Tugas 3:

Tindakan pencegahan agar insiden serupa tidak terulang

1. Jadikan route kritikal bagian dari smoke test

Bug produksi sering lolos karena pengujian hanya menyentuh homepage atau health endpoint. Masukkan API route penting, autentikasi, dan skenario data minimal.

2. Pakai migrasi yang kompatibel untuk rollback

Jika canary dan stable hidup bersamaan, desain perubahan database harus mendukung fase transisi. Hindari menghapus kolom atau mengganti format data secara langsung dalam satu langkah.

3. Versikan kontrak internal bila perlu

Jika route handler atau worker bergantung pada payload tertentu, pertimbangkan kompatibilitas versi agar stable tetap dapat berjalan saat rollback.

4. Tambahkan release marker di response header atau log

Ini membantu troubleshooting cepat saat membandingkan hasil request dari stable dan canary.

5. Bedakan readiness dari liveness

Banyak tim baru sadar pentingnya hal ini setelah insiden. Proses bisa hidup, tetapi belum siap menerima trafik karena dependency belum siap.

6. Gunakan canary gate yang jelas

Tetapkan kriteria naik atau berhenti, misalnya:

error rate tidak memburuk dibanding stable,
latency tidak naik signifikan,
smoke test lulus,
tidak ada alert aktif selama interval pengamatan.

Dengan gate yang jelas, keputusan tidak bergantung pada intuisi saat rilis sedang berjalan.

Kesalahan umum dalam canary deploy Next.js

Mengandalkan health check terlalu sederhana: hasilnya 200, tetapi route bisnis rusak.
Tidak membedakan metrik stable dan canary: regresi tertutup oleh trafik global.
Rollback berarti redeploy: ini memperlambat mitigasi. Gunakan traffic rollback lebih dulu.
Perubahan database tidak kompatibel: rollback infrastruktur berhasil, rollback fungsional gagal.
Canary terlalu besar di awal: jika ada bug, dampaknya langsung luas.

Penutup

Next.js: Canary Deploy App Router dengan rollback dan alerting paling efektif jika dibangun di atas empat fondasi: traffic splitting di level proxy/platform, health check yang benar, observability minimum yang tersegmentasi, dan prosedur rollback yang sederhana. Bukan sekadar memecah trafik, tetapi memastikan Anda bisa mendeteksi regresi cepat, mengurangi dampak ke pengguna, dan belajar dari insiden secara terstruktur.

Jika Anda baru memulai, jangan mengejar sistem yang terlalu kompleks. Mulailah dari dua deployment paralel, smoke test yang relevan, metrik inti, serta runbook rollback yang bisa dijalankan siapa pun di tim. Dari sana, Anda bisa menambah otomatisasi dan gate yang lebih ketat sesuai kebutuhan sistem.

Quick Search

shopping_cart Keranjang