Runbook deploy aman adalah dokumen operasional singkat yang menjawab tiga pertanyaan utama: apa yang harus dicek sebelum rilis, bagaimana memantau dampaknya setelah rilis, dan kapan harus rollback. Tanpa runbook, tim sering mengandalkan ingatan, chat, atau improvisasi saat produksi sedang bermasalah.

Untuk tim web/backend modern, runbook yang baik tidak harus panjang. Yang penting adalah urutan tindakan yang jelas, metrik inti yang dipantau, kriteria rollback yang objektif, dan cara menulis postmortem ringkas agar insiden kecil tidak terulang. Artikel ini fokus pada panduan praktis yang bisa diadopsi di pipeline deploy manual maupun CI/CD.

Apa yang Harus Ada dalam Runbook Deploy Aman

Minimal, sebuah runbook deploy aman perlu mencakup:

  • Checklist pra-rilis: memastikan perubahan siap dipromosikan ke produksi.
  • Health check: memverifikasi aplikasi benar-benar sehat, bukan sekadar prosesnya hidup.
  • Rollout bertahap: canary atau persentase trafik kecil sebelum full release.
  • Metrik inti: error rate, latency, dan saturation sebagai sinyal dini.
  • Alert pasca-rilis: pemantauan intensif dalam jendela waktu tertentu.
  • Kriteria rollback: aturan jelas kapan deploy dianggap gagal.
  • Langkah rollback minim risiko: urutan aman untuk kembali ke versi stabil.
  • Postmortem ringan: catatan belajar tanpa menyalahkan individu.

Prinsip pentingnya: deploy adalah perubahan pada sistem produksi, bukan sekadar proses kirim kode. Karena itu, runbook harus mencakup aplikasi, database, job asynchronous, cache, konfigurasi, dan dependensi eksternal.

Checklist Pra-Rilis yang Benar-Benar Berguna

Checklist pra-rilis sebaiknya singkat tetapi tegas. Tujuannya bukan menambah birokrasi, melainkan mengurangi kesalahan yang paling sering terjadi.

1. Validasi ruang lingkup perubahan

  • Apakah perubahan menyentuh jalur request kritis seperti login, checkout, billing, atau webhook?
  • Apakah ada perubahan skema database, index, atau migrasi data?
  • Apakah ada perubahan konfigurasi environment, secret, rate limit, atau timeout?
  • Apakah ada perubahan pada queue worker, cron, atau background job?
  • Apakah ada perubahan pada integrasi pihak ketiga?

Kenapa ini penting: level risiko deploy tidak sama. Perubahan CSS kecil berbeda dengan perubahan query utama pada endpoint yang trafiknya tinggi.

2. Pastikan artefak dan dependensi konsisten

  • Build dihasilkan dari commit yang jelas dan bisa dilacak.
  • Lockfile dependensi ikut ter-review jika ada perubahan paket.
  • Image/container atau artefak rilis dapat direproduksi.
  • Versi konfigurasi dan secret yang dibutuhkan sudah tersedia di environment target.

Kesalahan umum adalah kode sudah benar, tetapi image yang ter-deploy bukan hasil commit yang terakhir direview, atau environment production belum memiliki variabel yang dibutuhkan.

3. Verifikasi migrasi database aman

Jika deploy menyentuh database, gunakan pendekatan kompatibel maju-mundur (forward/backward compatible) bila memungkinkan:

  • Tambahkan kolom baru sebelum aplikasi mulai memakainya.
  • Hindari langsung menghapus kolom yang masih dibaca versi lama.
  • Untuk perubahan besar, pisahkan antara schema change dan data backfill.
  • Pastikan ada rencana rollback yang realistis jika migrasi gagal.

Rollback kode tidak selalu berarti rollback database aman. Jika migrasi bersifat destruktif, strategi rollback harus dipikirkan sebelum deploy, bukan saat insiden sudah terjadi.

4. Siapkan observability baseline

Sebelum deploy, catat baseline 15-30 menit terakhir untuk metrik utama:

  • Error rate: persentase request gagal atau respons 5xx.
  • Latency: median dan tail latency seperti p95/p99.
  • Saturation: CPU, memori, koneksi DB, queue backlog, thread/worker utilization.

Tanpa baseline, tim sering melihat dashboard setelah deploy lalu bingung apakah kenaikan latency itu normal atau efek rilis.

5. Verifikasi dependensi eksternal

  • Status provider pembayaran, email, object storage, atau auth service normal.
  • Tidak ada maintenance window dari vendor yang berdekatan dengan waktu deploy.
  • Retry, timeout, dan circuit breaker pada integrasi penting sudah masuk akal.

Deploy saat dependency eksternal sedang fluktuatif akan menyulitkan diagnosis. Jika insiden terjadi, tim tidak tahu apakah sumbernya dari perubahan internal atau layanan pihak ketiga.

Health Check yang Layak Dipakai Saat Deploy

Health check bukan hanya endpoint yang mengembalikan HTTP 200. Untuk runbook deploy aman, bedakan paling tidak dua jenis pemeriksaan.

Liveness vs readiness

  • Liveness: proses aplikasi masih hidup.
  • Readiness: instance siap menerima trafik secara aman.

Jika readiness terlalu dangkal, load balancer bisa mulai mengirim trafik ke instance yang sebenarnya belum siap: koneksi database belum stabil, cache belum warm, atau migrasi belum selesai.

Contoh respons health check yang berguna

GET /health/ready

{
  "status": "ok",
  "checks": {
    "app": "ok",
    "database": "ok",
    "queue": "ok",
    "external_auth": "degraded"
  },
  "release": "2026-06-08T10:15Z-abc123"
}

Yang penting bukan formatnya, melainkan isi informasinya. Endpoint readiness idealnya memberi sinyal apakah komponen minimum untuk melayani request sudah tersedia. Tidak semua dependensi harus memblokir readiness, tetapi dependensi kritis harus terlihat jelas.

Checklist health check pasca-deploy

  1. Pastikan versi rilis yang benar sudah aktif di instance target.
  2. Hit endpoint readiness dari luar pod/container, bukan hanya dari dalam proses.
  3. Uji satu atau dua alur bisnis inti: login, create order, submit API, atau enqueue job.
  4. Periksa log error 5-10 menit pertama setelah rollout dimulai.
  5. Pastikan queue, scheduler, dan worker yang relevan ikut sehat.

Kesalahan umum: tim hanya mengecek homepage atau endpoint ping sederhana, padahal masalah baru muncul pada endpoint autentikasi, query berat, atau background worker.

Rollout Bertahap: Canary Sederhana yang Realistis

Untuk sebagian besar tim, canary tidak harus rumit. Tujuannya adalah membatasi blast radius: jika ada bug, dampaknya hanya mengenai sebagian kecil trafik.

Pola rollout yang praktis

  • 1 instance dulu untuk environment dengan beberapa instance identik.
  • 5% - 10% trafik jika memakai load balancer atau service mesh yang mendukung weighted routing.
  • Satu AZ/region lebih dulu jika arsitektur multi-zone atau multi-region.
  • Internal/staff only dengan feature flag sebelum dibuka ke semua pengguna.

Pilih pola yang paling sederhana yang bisa dijalankan konsisten oleh tim. Canary manual yang disiplin lebih baik daripada mekanisme canggih yang jarang dipakai dan tidak dipahami saat insiden.

Jendela observasi setiap tahap

Jangan langsung menaikkan persentase trafik setelah deploy berhasil teknis. Sisakan waktu observasi pada tiap tahap, misalnya beberapa menit, untuk melihat:

  • Error rate naik dibanding baseline.
  • Tail latency memburuk pada endpoint inti.
  • Queue backlog bertambah.
  • Koneksi DB atau pool habis.
  • Log exception baru muncul berulang.

Canary bekerja karena Anda memberi waktu bagi sinyal masalah untuk muncul sebelum semua pengguna terdampak.

Contoh urutan rollout sederhana

  1. Deploy ke 1 instance canary.
  2. Jalankan smoke test dan health check.
  3. Observasi 5-10 menit pada metrik inti.
  4. Naikkan ke 25% trafik atau beberapa instance tambahan.
  5. Observasi lagi.
  6. Lanjutkan ke 100% jika metrik tetap dalam batas normal.

Metrik Inti dan Alert Pasca-Rilis

Runbook deploy aman tidak perlu memantau puluhan panel. Fokus dulu pada tiga sinyal utama dari operasi sistem: error rate, latency, dan saturation.

1. Error rate

Gunakan metrik yang paling dekat dengan kegagalan yang dirasakan pengguna:

  • HTTP 5xx meningkat.
  • RPC error meningkat.
  • Job queue gagal/retry melonjak.
  • Database error atau timeout naik.

Jika memungkinkan, pisahkan antara error karena validasi pengguna dan error sistem. Deploy biasanya lebih relevan terhadap error sistem.

2. Latency

Jangan hanya melihat rata-rata. Pantau tail latency seperti p95 atau p99 untuk endpoint penting. Rata-rata bisa terlihat baik padahal sebagian kecil request sudah sangat lambat.

3. Saturation

Saturation menunjukkan seberapa dekat resource ke batas kapasitas:

  • CPU tinggi berkepanjangan.
  • Memori meningkat atau terjadi restart karena out-of-memory.
  • Pool koneksi database hampir habis.
  • Queue backlog tumbuh terus.
  • Disk I/O atau throughput jaringan menjadi bottleneck.

Kenapa saturation penting: kadang deploy tidak langsung menimbulkan error, tetapi membuat sistem lebih mahal dan rapuh. Beberapa menit kemudian barulah timeout mulai muncul.

Alert pasca-rilis yang perlu diaktifkan

Setelah deploy dimulai, aktifkan atau perhatikan alert dengan horizon pendek, misalnya 15-30 menit pertama:

  • Error rate layanan utama melewati ambang normal.
  • Latency p95 endpoint kritis naik signifikan dari baseline.
  • Restart container/pod bertambah.
  • Queue backlog terus naik tanpa turun.
  • Dependensi eksternal mengembalikan timeout atau 5xx lebih sering.

Idealnya, runbook menetapkan siapa yang memonitor, di channel mana, dan selama berapa lama setelah rilis penuh selesai.

Kriteria Rollback yang Jelas dan Tidak Ambigu

Salah satu penyebab insiden membesar adalah tim terlalu lama berdebat apakah perlu rollback. Karena itu, tentukan kriteria rollback sebelum deploy.

Contoh kriteria rollback

  • Error rate melewati ambang yang melanggar SLO layanan.
  • Latency p95 endpoint inti meningkat konsisten dibanding baseline dalam jendela observasi.
  • Terjadi error pada alur bisnis utama: login gagal, checkout gagal, webhook tidak terproses.
  • Queue backlog tumbuh dan tidak pulih setelah beberapa menit.
  • Readiness/liveness instance baru tidak stabil.
  • Terjadi peningkatan exception baru yang jelas berkorelasi dengan rilis.

SLO berguna di sini sebagai pagar keputusan. Jika perubahan membuat indikator layanan keluar dari target yang disepakati, rollback bukan keputusan emosional, melainkan respons operasional yang objektif.

Jika tim belum punya SLO formal, gunakan ambang operasional sementara berbasis baseline. Yang penting adalah kriterianya tertulis dan disepakati sebelum deploy dimulai.

Kapan tidak perlu rollback langsung?

Tidak semua alarm berarti rollback. Contohnya:

  • Lonjakan kecil yang hanya terjadi sesaat saat cache warm-up dan cepat stabil.
  • Error non-kritis pada jalur yang tidak aktif untuk mayoritas trafik.
  • Masalah murni dari vendor eksternal yang sudah teridentifikasi dan tidak terkait rilis.

Namun hati-hati dengan bias konfirmasi. Jangan memaksa menjelaskan semua gejala sebagai “normal” hanya karena deploy sudah telanjur berjalan.

Langkah Rollback Minim Risiko

Rollback yang aman harus sesederhana mungkin, bisa dijalankan cepat, dan tidak menambah perubahan baru. Tujuannya adalah mengembalikan layanan ke keadaan stabil, bukan memperbaiki semua akar masalah saat itu juga.

Prinsip rollback

  • Kembalikan ke artefak rilis terakhir yang diketahui stabil.
  • Hindari perubahan tambahan di tengah rollback.
  • Jika ada feature flag, matikan fitur baru sebelum rollback penuh bila itu cukup mengurangi risiko.
  • Komunikasikan status rollback ke tim agar tidak ada deploy lain berjalan bersamaan.

Urutan rollback yang praktis

  1. Hentikan promosi rollout ke instance atau trafik lain.
  2. Nonaktifkan feature flag yang terkait jika tersedia.
  3. Alihkan trafik kembali ke versi stabil atau turunkan weight canary ke nol.
  4. Redeploy artefak stabil terakhir bila diperlukan.
  5. Verifikasi health check dan smoke test pada versi stabil.
  6. Pantau metrik hingga error rate, latency, dan saturation kembali ke baseline.
  7. Bekukan deploy lanjutan sampai ada analisis singkat.

Contoh perintah yang bersifat generik

# Contoh alur rollback generik, sesuaikan dengan platform Anda
releasectl pause-rollout service-api
feature-flag disable checkout_v2
trafficctl set-weight service-api canary=0 stable=100
releasectl rollback service-api --to release-previous-stable
healthcheck verify service-api
observability watch service-api --window 15m

Nama perintah di atas hanya ilustrasi. Yang penting, runbook tim Anda harus menyebutkan alat sebenarnya, siapa yang berwenang menjalankan, dan verifikasi apa yang wajib dilakukan setelah rollback.

Trade-off rollback

  • Cepat, tetapi tidak selalu mudah jika ada migrasi database destruktif.
  • Aman, tetapi mungkin membuat perubahan valid ikut tertunda.
  • Sederhana, tetapi kurang efektif jika akar masalah ada pada konfigurasi atau dependency eksternal.

Karena itu, prevention seperti feature flag dan migrasi kompatibel sering lebih berharga daripada rollback yang “heroic”.

Tindakan Pencegahan Sebelum Insiden Terjadi

1. Gunakan feature flag untuk memisahkan deploy dan release

Deploy kode ke produksi tidak harus langsung mengaktifkan fitur ke semua pengguna. Dengan feature flag, tim bisa:

  • Menguji pada internal user dulu.
  • Membuka bertahap per segmen pengguna.
  • Mematikan fitur tanpa redeploy penuh jika ada gejala buruk.

Trade-off-nya adalah kompleksitas tambahan. Flag yang tidak pernah dibersihkan akan menambah cabang logika dan risiko perilaku yang sulit diprediksi.

2. Siapkan observability baseline per layanan penting

Setiap layanan inti sebaiknya punya dashboard minimum yang sama:

  • Request volume.
  • Error rate.
  • Latency p50/p95/p99.
  • Status dependency utama.
  • CPU, memori, restart, koneksi DB, queue backlog.

Ini mempersingkat diagnosis. Saat deploy bermasalah, tim tidak perlu merakit panel ad-hoc sambil panik.

3. Verifikasi dependency eksternal dan fallback

Jika layanan bergantung pada payment gateway, email, auth provider, atau API partner:

  • Pastikan timeout tidak terlalu panjang.
  • Gunakan retry dengan batas yang masuk akal.
  • Pertimbangkan circuit breaker untuk mencegah cascading failure.
  • Sediakan mode degradasi bila memungkinkan, misalnya menunda sinkronisasi non-kritis.

Kesalahan umum adalah retry tanpa batas atau timeout terlalu lama, yang justru memperburuk saturation saat dependency sedang lambat.

Contoh Runbook Deploy Aman yang Ringkas

Runbook Deploy - service-api

Pra-rilis:
1. Pastikan PR sudah direview dan test utama lulus.
2. Konfirmasi migrasi DB kompatibel dengan versi lama.
3. Verifikasi env var, secret, dan endpoint dependency tersedia.
4. Catat baseline 30 menit terakhir: error rate, p95 latency, CPU/memori, queue backlog.
5. Umumkan jadwal deploy di channel operasional.

Deploy:
1. Deploy ke 1 instance canary.
2. Jalankan readiness check dan smoke test endpoint kritis.
3. Observasi 10 menit.
4. Jika stabil, naikkan ke 25%, lalu 100%.

Pantau pasca-rilis:
- Error rate
- Latency p95
- Saturation: CPU, memori, DB connection, queue backlog
- Error dependency eksternal

Rollback jika:
- SLO terlanggar
- Error rate meningkat konsisten
- p95 endpoint kritis memburuk signifikan
- Checkout/login/job penting gagal

Rollback:
1. Pause rollout.
2. Disable feature flag terkait.
3. Arahkan trafik ke versi stabil.
4. Redeploy artefak stabil terakhir bila perlu.
5. Verifikasi health check dan metrik kembali normal.

Setelah insiden:
- Buat timeline singkat
- Catat dampak, akar penyebab sementara, tindakan pencegahan
- Jangan deploy ulang sampai mitigasi disepakati

Contoh Timeline Insiden Kecil

Insiden kecil tetap layak didokumentasikan jika menyebabkan degradasi layanan, meski tidak sampai outage total. Format timeline membantu tim melihat fakta tanpa asumsi.

  • 10:00 - Deploy versi baru dimulai ke 1 instance canary.
  • 10:04 - Readiness check lolos, smoke test login berhasil.
  • 10:08 - Error rate endpoint /checkout mulai naik.
  • 10:10 - Latency p95 checkout meningkat, queue order backlog bertambah.
  • 10:12 - Rollout dihentikan, feature flag fitur promo baru dimatikan.
  • 10:14 - Trafik canary di-set ke 0%.
  • 10:18 - Metrik mulai pulih ke baseline.
  • 10:25 - Ditemukan query baru tidak memakai index yang sesuai pada jalur checkout.
  • 10:40 - Insiden ditutup, deploy dibekukan sampai perbaikan diverifikasi.

Timeline seperti ini cukup untuk insiden kecil. Fokusnya pada urutan kejadian, sinyal yang diamati, dan tindakan yang diambil.

Template Postmortem Ringan Tanpa Blame

Postmortem ringan cocok untuk tim yang ingin belajar cepat tanpa menunggu dokumen panjang. Yang penting adalah fakta, dampak, akar masalah, dan pencegahan.

Postmortem Ringkas

Judul:
Degradasi checkout setelah deploy service-api

Ringkasan:
Setelah deploy bertahap, endpoint checkout mengalami kenaikan latency dan error rate.
Rollout dihentikan dan trafik dikembalikan ke versi stabil.

Dampak:
- Periode: 10:08 - 10:18
- Gejala: checkout lambat dan sebagian request gagal
- Area terdampak: pengguna yang masuk ke canary

Deteksi:
- Alert error rate dan p95 latency
- Kenaikan queue backlog pada worker order

Akar penyebab:
- Query baru pada jalur checkout memicu load DB lebih tinggi dari baseline
- Canary lolos smoke test, tetapi beban nyata memperlihatkan masalah performa

Faktor kontribusi:
- Tidak ada analisis query plan untuk perubahan ini
- Dashboard DB connection tidak dipantau aktif saat rollout awal

Mitigasi yang dilakukan:
- Pause rollout
- Disable feature flag terkait
- Set canary traffic ke 0%

Yang berjalan baik:
- Alert cepat terpicu
- Rollback minim risiko berhasil
- Blast radius kecil karena rollout bertahap

Yang perlu diperbaiki:
- Tambahkan pemeriksaan query plan pada PR berisiko tinggi
- Tambahkan checklist observasi DB saturation saat canary
- Perjelas ambang rollback untuk endpoint checkout

Action items:
1. Tambah dashboard koneksi DB dan slow query untuk deploy window
2. Wajibkan review performa untuk perubahan query kritis
3. Uji beban ringan untuk endpoint checkout sebelum rilis berikutnya

Hindari bahasa yang menyalahkan orang, misalnya “developer A lupa”. Gunakan bahasa sistemik: pengaman apa yang tidak ada, sinyal apa yang terlewat, proses apa yang perlu ditambah.

Kesalahan yang Paling Sering Terjadi

  • Tidak ada ambang rollback yang tertulis, sehingga keputusan terlambat.
  • Health check terlalu dangkal, hanya memastikan proses hidup.
  • Canary terlalu singkat, tidak memberi waktu munculnya gejala.
  • Deploy dan migrasi destruktif dilakukan sekaligus tanpa strategi kompatibilitas.
  • Dashboard terlalu ramai, tetapi tidak ada 3-5 metrik inti yang benar-benar diawasi.
  • Melupakan queue dan worker, padahal banyak dampak deploy baru terlihat di sistem asynchronous.
  • Mengabaikan dependency eksternal, sehingga diagnosis menjadi salah arah.

Penutup

Runbook deploy aman tidak harus kompleks. Nilainya ada pada keputusan yang bisa diulang saat tekanan tinggi: apa yang dicek sebelum rilis, metrik apa yang dipantau, kapan rollback wajib dilakukan, dan bagaimana mencatat pelajaran setelahnya.

Jika tim Anda belum punya runbook formal, mulai dari versi satu halaman: checklist pra-rilis, health check yang benar, canary sederhana, tiga metrik inti, kriteria rollback, dan template postmortem ringkas. Setelah beberapa deploy, evaluasi dan rapikan berdasarkan insiden nyata. Runbook yang dipakai rutin selalu lebih berguna daripada dokumen panjang yang hanya tersimpan di wiki.