Runbook deployment aman bukan dokumen formal yang disimpan lalu dilupakan. Ia harus bisa dipakai saat tekanan tinggi: langkahnya jelas, sinyal keberhasilannya terukur, dan jalur mundurnya cepat. Jika deployment terasa seperti alat kerja yang nyaman dipakai setiap hari—mudah ditekan, responsnya konsisten, dan tidak memberi kejutan—tim lebih kecil kemungkinannya membuat kesalahan saat rilis.

Prinsip ini mirip dengan memilih perangkat kerja yang ergonomis dan reliabel: nyaman dijalankan, mudah diamati, cepat dibatalkan, dan minim kejutan. Dalam praktik deployment, itu berarti proses rilis harus sederhana dioperasikan, observabilitas tersedia sebelum deploy dimulai, rollback tidak bergantung pada improvisasi, dan perubahan berisiko tinggi dipagari dengan canary, health check, serta trigger go/no-go yang jelas.

Prinsip operasional runbook deployment aman

Sebelum masuk ke langkah teknis, tetapkan empat prinsip berikut sebagai standar operasional:

  • Nyaman dijalankan: perintah deploy pendek, terdokumentasi, tidak perlu banyak keputusan manual di tengah jalan.
  • Mudah diamati: metrik, log, dan tracing sudah tersedia sebelum rilis, bukan dipasang setelah insiden.
  • Cepat dibatalkan: rollback punya jalur eksekusi jelas, termasuk untuk aplikasi, konfigurasi, dan skema database.
  • Minim kejutan: perubahan kecil, bertahap, dan bisa dihentikan cepat lewat canary atau pembatasan trafik.

Prinsip ini bekerja karena deployment gagal jarang disebabkan satu bug saja. Yang sering memperburuk dampak adalah proses yang terlalu rumit, sinyal observasi yang tidak siap, serta rollback yang ternyata tidak benar-benar aman.

Checklist pra-deploy yang wajib ada

Checklist pra-deploy berfungsi mengurangi kejutan. Fokusnya bukan menambah birokrasi, tetapi memastikan semua prasyarat operasional tersedia.

1. Validasi perubahan

  • Pastikan scope perubahan jelas: kode aplikasi, konfigurasi, migrasi database, perubahan dependency, atau infrastruktur.
  • Identifikasi komponen yang terdampak: API publik, worker queue, cache, scheduler, webhook, atau integrasi pihak ketiga.
  • Pastikan ada referensi commit, tag, atau image yang akan dirilis dan versi sebelumnya yang siap dipakai untuk rollback.

2. Pastikan rollback memang mungkin

  • Aplikasi stateless biasanya mudah di-rollback ke image atau release sebelumnya.
  • Perubahan database lebih rumit. Hindari perubahan destruktif dalam satu langkah, misalnya langsung menghapus kolom yang masih dipakai versi lama.
  • Gunakan pola expand and contract: tambah struktur baru dulu, deploy aplikasi yang kompatibel dengan lama dan baru, migrasikan data bila perlu, baru hapus struktur lama di rilis berikutnya.

Kesalahan umum: tim merasa rollback aman karena image lama masih ada, padahal skema database sudah berubah tidak kompatibel. Hasilnya, rollback aplikasi justru memperparah insiden.

3. Verifikasi observabilitas sebelum deploy

  • Dashboard metrik utama tersedia dan sudah dipahami operator.
  • Log terpusat bisa difilter berdasarkan versi rilis, pod/instance, atau endpoint.
  • Tracing tersedia untuk request penting agar lonjakan latensi bisa ditelusuri ke service atau query tertentu.
  • Alert sementara atau panel fokus rilis disiapkan untuk durasi deployment.

4. Tentukan sinyal go/no-go

Jangan mulai deploy tanpa kriteria keputusan. Minimal tetapkan:

  • Go: error rate stabil, latensi tidak naik signifikan, health check hijau, antrian tidak menumpuk, dan tidak ada log error baru yang dominan.
  • No-go: error 5xx meningkat, timeout bertambah, saturation CPU/memori tinggi pada instance canary, error query/database muncul, atau integrasi downstream gagal.

5. Persiapan operasional

  • Tentukan penanggung jawab deploy dan peninjau observabilitas.
  • Hindari deploy saat tim kunci tidak tersedia, kecuali ada kebutuhan insiden.
  • Bekukan perubahan lain yang bisa mengaburkan analisis, seperti edit konfigurasi mendadak di tengah rilis.
  • Pastikan feature flag atau toggle tersedia untuk fitur berisiko tinggi.

Canary release: cara aman mengurangi blast radius

Canary release berarti hanya sebagian kecil trafik yang diarahkan ke versi baru lebih dulu. Tujuannya bukan sekadar “deploy bertahap”, tetapi memberi waktu untuk mengamati perilaku versi baru dengan dampak terbatas.

Kapan canary paling berguna

  • Perubahan menyentuh jalur request utama.
  • Ada perubahan query, cache behavior, atau dependency eksternal.
  • Service bertrafik tinggi sehingga masalah akan cepat terlihat.
  • Tim butuh bukti produksi sebelum menaikkan trafik penuh.

Pola rollout sederhana

  1. Deploy versi baru ke sebagian kecil instance.
  2. Arahkan persentase kecil trafik ke instance canary.
  3. Amati metrik inti selama jendela observasi yang disepakati.
  4. Jika stabil, naikkan trafik bertahap.
  5. Jika ada anomali, hentikan promosi atau rollback.

Angka persentase dan durasi observasi bergantung pada volume trafik serta risiko perubahan. Untuk service bertrafik rendah, canary mungkin butuh waktu lebih lama agar sinyal cukup bermakna. Untuk trafik tinggi, sinyal bisa muncul lebih cepat tetapi noise juga perlu dibedakan dari tren nyata.

Contoh alur runbook canary

Tujuan: merilis versi backend baru dengan blast radius minimum

1. Verifikasi image/tag rilis dan versi rollback.
2. Pastikan dashboard rilis aktif:
   - error rate
   - p95/p99 latency
   - throughput
   - CPU/memory
   - database errors
   - queue backlog
3. Deploy ke instance canary.
4. Jalankan smoke test pada endpoint kritis.
5. Arahkan trafik kecil ke canary.
6. Observasi selama jendela yang disepakati.
7. Jika semua sinyal go, naikkan trafik bertahap.
8. Jika muncul sinyal no-go, hentikan promosi dan rollback canary.
9. Setelah full rollout, lanjutkan observasi pasca-deploy.

Health check yang berguna, bukan sekadar formalitas

Health check sebaiknya dibagi menurut tujuannya:

  • Liveness: proses masih hidup. Jangan isi dengan cek berat atau dependency eksternal.
  • Readiness: instance siap menerima trafik. Ini tempat yang tepat untuk mengecek dependensi minimum yang wajib ada, misalnya koneksi database atau konfigurasi penting sudah termuat.
  • Smoke check aplikasi: verifikasi jalur penting setelah deploy, misalnya login, create order, atau endpoint internal kritis.

Kesalahan umum adalah membuat health check terlalu dangkal, misalnya hanya mengembalikan HTTP 200 tanpa menguji kesiapan aplikasi. Akibatnya, load balancer mengirim trafik ke instance yang secara teknis hidup tetapi belum benar-benar siap.

Metrik inti, log, dan tracing untuk keputusan go/no-go

Deployment aman bergantung pada sinyal yang mudah dibaca. Jangan mencoba melihat semua hal sekaligus. Mulailah dari metrik inti yang paling dekat dengan pengalaman pengguna dan stabilitas sistem.

Metrik inti yang perlu dipantau

  • Error rate: 5xx, timeout, atau exception yang meningkat setelah canary.
  • Latency: terutama p95 atau p99 untuk endpoint penting, bukan hanya rata-rata.
  • Traffic/throughput: memastikan penurunan error bukan karena trafik hilang.
  • Saturation: CPU, memory, thread pool, koneksi database, queue backlog.
  • Dependency health: error ke database, cache, broker, dan API eksternal.
  • Business metric minimum: misalnya tingkat checkout berhasil, request login sukses, atau job penting terselesaikan.

Log yang benar-benar membantu saat deploy

Log harus bisa menjawab: versi mana yang gagal, request mana yang terdampak, dan error dominannya apa? Karena itu:

  • Sertakan identifier versi rilis atau commit pada log.
  • Gunakan log terstruktur bila memungkinkan.
  • Pastikan error log memuat konteks cukup: endpoint, status code, dependency yang gagal, dan correlation/request id.
  • Hindari flood log yang membuat sinyal penting tenggelam.

Tracing untuk menemukan sumber latensi

Jika setelah canary latensi naik tetapi error belum terlihat, tracing sangat berguna. Anda bisa membedakan apakah masalah ada di:

  • query database yang melambat,
  • panggilan API eksternal,
  • lock contention,
  • cache miss yang meningkat, atau
  • serialisasi payload yang membesar.

Tanpa tracing, tim sering menebak-nebak dan memperlambat keputusan rollback.

Trigger rollback: kapan harus berhenti maju

Rollback yang baik dimulai dari trigger yang tegas. Jangan menunggu semua metrik rusak. Biasanya cukup satu atau dua sinyal kuat untuk menghentikan rollout.

Contoh trigger rollback yang masuk akal

  • Error 5xx atau timeout naik konsisten setelah canary aktif.
  • Latensi p95/p99 naik dan berdampak pada endpoint utama.
  • Readiness gagal pada banyak instance baru.
  • Queue backlog tumbuh karena worker baru tidak stabil.
  • Error database meningkat, misalnya deadlock, timeout, atau query plan memburuk.
  • Business metric kritis turun, misalnya transaksi gagal atau login sukses menurun.

Prinsip penting: jika operator harus berdebat terlalu lama saat sinyal buruk muncul, runbook belum cukup jelas. Trigger rollback harus tertulis sebelum deploy dimulai.

Sinyal yang belum tentu butuh rollback penuh

  • Lonjakan warning yang tidak memengaruhi jalur kritis.
  • Noise observasi singkat yang tidak konsisten.
  • Error dari trafik bot atau endpoint non-kritis yang sudah diketahui.

Namun hati-hati: jangan memakai alasan ini untuk menunda keputusan yang seharusnya cepat.

Langkah rollback aman yang benar-benar bisa dieksekusi

Rollback aman bukan sekadar “deploy versi sebelumnya”. Ia harus mempertimbangkan trafik, kompatibilitas data, background job, dan perubahan konfigurasi.

Urutan rollback yang disarankan

  1. Hentikan promosi rollout: jangan tambah trafik ke versi baru.
  2. Isolasi canary: arahkan trafik baru kembali ke versi stabil.
  3. Rollback aplikasi: gunakan image, release, atau artifact yang sudah tervalidasi sebelumnya.
  4. Verifikasi health check dan smoke test pada versi yang dipulihkan.
  5. Pantau pemulihan metrik: pastikan error dan latensi kembali ke baseline yang wajar.
  6. Tangani pekerjaan tertunda: queue, job retry, atau event yang mungkin tertumpuk selama insiden.
  7. Evaluasi kebutuhan rollback konfigurasi atau feature flag.

Perhatian khusus untuk database

Rollback database adalah area paling rawan. Beberapa aturan praktis:

  • Jangan mengandalkan rollback migrasi destruktif sebagai jalur utama.
  • Untuk kolom/field baru, buat aplikasi kompatibel dua arah selama masa transisi.
  • Jika ada backfill data, pastikan rollback aplikasi tidak memecahkan pembacaan data hasil migrasi.
  • Jika perubahan menyentuh indeks atau query besar, siapkan rencana observasi pasca-rollback karena dampak bisa bertahan sesaat.

Contoh template langkah rollback

Rollback Plan

Kondisi pemicu:
- error rate naik konsisten setelah canary
- readiness gagal pada instance baru
- business metric kritis turun

Langkah:
1. Pause rollout.
2. Route traffic kembali ke stable.
3. Deploy artifact versi sebelumnya.
4. Pastikan readiness/liveness hijau.
5. Jalankan smoke test endpoint kritis.
6. Monitor 10-30 menit sesuai volume trafik.
7. Jika sistem pulih, umumkan rollback selesai.
8. Bekukan deploy lanjutan sampai analisis awal selesai.

Kesalahan umum yang membuat rollback gagal

  • Tidak tahu versi stabil terakhir karena artifact tidak ditandai rapi.
  • Rollback hanya untuk aplikasi, tetapi konfigurasi runtime atau secret juga berubah.
  • Migrasi database tidak kompatibel mundur.
  • Queue/worker tetap memproses payload format baru saat aplikasi sudah di-rollback.
  • Cache tidak dipikirkan: skema cache baru membuat versi lama salah membaca data.
  • Observabilitas rollback tidak dipantau, sehingga tim mengira pemulihan selesai padahal masalah bergeser ke komponen lain.

Contoh runbook deployment aman untuk tim web/backend

Berikut contoh runbook ringkas yang bisa diadaptasi. Tujuannya bukan mengikuti format ini mentah-mentah, tetapi memastikan keputusan teknis dan operasional tertulis.

Template runbook

Nama layanan: payment-api
Perubahan: optimasi query settlement + pembaruan endpoint internal
Risiko utama: latensi database, payload queue, kompatibilitas cache
Operator: on-call backend
Reviewer observabilitas: SRE/platform
Versi rilis: release-2026-xx
Versi rollback: release-sebelumnya

Pra-deploy:
- CI lulus
- smoke test staging lulus
- migrasi database bersifat additive
- dashboard rilis siap
- feature flag tersedia untuk jalur baru

Canary:
- deploy ke subset instance
- arahkan trafik kecil
- observasi error rate, p95 latency, DB error, queue backlog
- jalankan smoke test login, create payment, webhook callback

Go jika:
- health check hijau
- tidak ada kenaikan error yang konsisten
- latensi endpoint utama stabil
- queue backlog tidak tumbuh abnormal

No-go jika:
- timeout meningkat
- DB error muncul setelah canary
- callback payment gagal
- readiness flapping

Rollback:
- pause rollout
- route traffic ke stable
- redeploy release-sebelumnya
- verifikasi smoke test
- monitor pemulihan

Pasca-deploy:
- pantau 30-60 menit sesuai trafik
- catat anomali kecil sekalipun
- jadwalkan tindak lanjut jika ada degradasi non-kritis

Postmortem ringan: cepat, jujur, dan bisa ditindaklanjuti

Tidak semua insiden butuh dokumen panjang. Untuk deployment yang bermasalah, postmortem ringan biasanya cukup jika fokus pada fakta, dampak, akar masalah, dan pencegahan. Tujuannya bukan mencari siapa yang salah, tetapi memperbaiki sistem kerja agar kejadian serupa tidak berulang.

Kapan cukup memakai postmortem ringan

  • Insiden pulih cepat dan dampak terbatas.
  • Akar masalah relatif jelas.
  • Tidak ada pelanggaran keamanan besar atau dampak regulasi.
  • Yang dibutuhkan terutama perbaikan runbook, test, atau observabilitas.

Template postmortem ringan

Judul insiden:
Deployment payment-api menyebabkan kenaikan timeout pada endpoint checkout

Ringkasan:
Setelah canary, timeout meningkat pada endpoint checkout. Rollback dilakukan dan layanan pulih.

Dampak:
- sebagian request checkout gagal/timeout
- durasi insiden: [isi waktu]
- area terdampak: [endpoint/fitur]

Timeline singkat:
- 10:00 deploy canary dimulai
- 10:05 timeout naik
- 10:08 rollout dipause
- 10:12 rollback selesai
- 10:20 metrik kembali stabil

Akar masalah:
- query baru tidak efisien pada pola data produksi tertentu

Deteksi:
- alert latency p95
- log query timeout
- tracing menunjukkan bottleneck di database

Yang berjalan baik:
- canary membatasi blast radius
- rollback cepat karena artifact stabil tersedia

Yang kurang:
- tidak ada test performa untuk query baru
- trigger rollback belum otomatis terlihat di dashboard utama

Tindakan pencegahan:
- tambah review query plan untuk perubahan database
- tambah smoke/performance check untuk endpoint checkout
- tampilkan metrik DB timeout di panel deploy

Owner dan target waktu:
- [nama/tim] - [tanggal]

Tindakan pencegahan agar insiden tidak berulang

Pencegahan terbaik bukan menambah banyak rapat, melainkan memperkuat titik yang paling sering gagal dalam siklus deploy.

Perbaikan yang paling berdampak

  • Kecilkan ukuran perubahan: rilis kecil lebih mudah diamati dan di-rollback.
  • Gunakan feature flag untuk mematikan perilaku baru tanpa harus selalu redeploy.
  • Bangun kompatibilitas mundur pada skema data, payload queue, dan cache key.
  • Automasi smoke test untuk jalur bisnis inti setelah canary.
  • Standarkan dashboard deploy agar operator tidak mencari sinyal di banyak tempat.
  • Latihan rollback secara berkala, karena rollback yang tidak pernah diuji sering gagal saat dibutuhkan.

Debugging tips saat canary tampak aneh

  • Bandingkan metrik versi lama dan baru pada endpoint yang sama, bukan agregat seluruh sistem.
  • Periksa apakah trafik canary mewakili pola nyata atau hanya subset tertentu.
  • Lihat perubahan pada payload size, query count, dan cache hit ratio.
  • Jangan abaikan background worker; banyak insiden tampak “baik” di API tetapi rusak di proses asinkron.
  • Pastikan clock, zona waktu, dan konfigurasi environment tidak berbeda antara stable dan canary.

Penutup

Runbook deployment aman yang baik terasa seperti alat kerja yang reliabel: nyaman dipakai, jelas responsnya, dan tidak mengejutkan operator. Dalam konteks web/backend, itu berarti checklist pra-deploy yang tegas, canary release untuk membatasi risiko, health check yang bermakna, metrik dan tracing yang siap dipakai, rollback yang kompatibel dengan data, serta postmortem ringan yang menghasilkan tindakan nyata.

Jika tim Anda hanya mengambil satu langkah setelah membaca panduan ini, mulailah dari dua hal: tulis trigger rollback yang eksplisit dan uji jalur rollback pada perubahan berikutnya. Banyak deployment gagal bukan karena bug tak terduga, tetapi karena tim terlalu lama maju saat seharusnya berhenti.