Runbook deployment yang baik tidak dimulai saat sistem sudah gagal total. Ia dimulai dari kemampuan tim mengenali gejala kecil—latensi yang naik tipis, error rate yang mulai bergeser, antrean worker yang menumpuk, atau log anomali yang belum memicu alarm besar—lalu mengambil keputusan yang terukur: lanjut, tahan, atau rollback.

Prinsipnya mirip proses inspeksi sistematis saat membongkar perangkat keras: jangan langsung menyimpulkan sumber masalah dari satu tanda. Amati bagian luar, cek sambungan, lihat pola keausan, lalu bongkar bertahap dengan urutan yang aman. Dalam deployment, pendekatan ini berarti mulai dari gejala, validasi sinyal, batasi blast radius, dan siapkan rollback yang benar-benar bisa dijalankan, bukan sekadar tertulis di dokumen.

Mengapa runbook deployment harus berbasis gejala kecil

Banyak insiden produksi tidak dimulai dari alarm merah, tetapi dari perubahan kecil yang diabaikan. Misalnya:

  • p95 latency naik perlahan setelah deploy, tetapi belum melampaui SLO,
  • error 5xx hanya naik di satu endpoint,
  • consumer queue masih berjalan, tetapi lag terus bertambah,
  • log warning baru muncul berulang setelah versi baru aktif.

Jika runbook hanya berisi langkah saat sistem sudah jatuh, tim kehilangan jendela terbaik untuk intervensi. Runbook yang lebih berguna justru mendefinisikan:

  • gejala awal yang perlu diamati,
  • ambang keputusan untuk lanjut, tahan, atau rollback,
  • urutan tindakan agar perubahan bisa dibatalkan tanpa memperparah keadaan.

Pendekatan ini juga mengurangi keputusan impulsif. Tidak semua anomali butuh rollback langsung, tetapi setiap anomali harus punya cara verifikasi yang jelas.

Checklist pra-deploy yang benar-benar berguna

Checklist pra-deploy bukan daftar seremonial. Tujuannya adalah mengurangi kegagalan yang seharusnya bisa dicegah sebelum perubahan menyentuh produksi.

1. Validasi perubahan dan risiko

  • Apakah perubahan menyentuh jalur kritis seperti autentikasi, pembayaran, checkout, atau pipeline data?
  • Apakah ada perubahan pada schema database, format event, kontrak API, atau konfigurasi queue?
  • Apakah perubahan bersifat backward compatible?
  • Apakah ada dependensi ke layanan eksternal yang sedang tidak stabil?

Jika ada perubahan yang tidak kompatibel ke belakang, rollback menjadi jauh lebih sulit. Ini harus terlihat jelas sebelum deploy dimulai.

2. Pastikan artefak dan konfigurasi konsisten

  • Image/container yang akan dirilis sudah teridentifikasi jelas.
  • Variabel lingkungan dan secret untuk versi baru sudah tersedia.
  • Konfigurasi tidak berubah diam-diam di luar mekanisme yang dilacak.
  • Migration, job, dan perubahan konfigurasi direncanakan urutannya.

Kesalahan umum di sini adalah aplikasi baru membutuhkan konfigurasi baru, tetapi server lama atau worker lama belum mendapatkannya. Hasilnya bukan crash total, melainkan gejala kecil yang sulit dibaca.

3. Verifikasi observability sebelum deploy

Jangan mulai deploy jika Anda tidak bisa melihat dampaknya. Minimal siapkan:

  • dashboard latency, throughput, error rate, dan saturation,
  • dashboard queue depth atau consumer lag bila ada worker,
  • akses ke log terpusat,
  • alert yang relevan, atau setidaknya kueri manual yang sudah disiapkan.

Runbook deployment tanpa observability pada praktiknya hanya mengandalkan tebakan.

4. Tetapkan peran dan jalur komunikasi

  • Siapa operator deploy?
  • Siapa pengambil keputusan jika gejala muncul?
  • Di kanal mana status akan diumumkan?
  • Siapa yang siap menangani database, aplikasi, dan infrastruktur bila perlu?

Untuk tim kecil, satu orang bisa memegang beberapa peran, tetapi tetap perlu ditulis. Saat muncul tekanan, kejelasan peran mengurangi kebingungan.

5. Siapkan rollback sebelum deploy, bukan sesudahnya

Rollback plan harus spesifik:

  • versi stabil terakhir yang akan dipakai,
  • langkah rollback aplikasi,
  • status migration database,
  • status worker dan job in-flight,
  • verifikasi setelah rollback selesai.

Catatan: rollback aplikasi biasanya mudah. Rollback data hampir selalu lebih sulit. Karena itu, desain perubahan schema sebaiknya mengutamakan kompatibilitas dua arah selama masa transisi.

Sinyal observability awal yang perlu masuk ke runbook deployment

Empat kategori sinyal berikut cukup praktis untuk hampir semua sistem layanan web dan worker: latency, error rate, saturation, dan anomali log.

Latency: jangan hanya lihat rata-rata

Gunakan persentil seperti p95 atau p99 jika tersedia. Rata-rata sering menutupi degradasi pada sebagian pengguna.

  • Lihat endpoint atau operasi kritis, bukan metrik global saja.
  • Bandingkan sebelum dan sesudah deploy dalam jendela waktu pendek.
  • Perhatikan apakah lonjakan konsisten atau hanya spike sesaat akibat warm-up.

Contoh gejala kecil: p95 endpoint checkout naik setelah 10% traffic canary masuk. Belum gagal, tetapi cukup untuk menahan rollout penuh.

Error rate: bedakan noise dan pola baru

Tidak semua error berarti rollback. Yang perlu dicari adalah perubahan pola:

  • kode 5xx naik pada rute tertentu,
  • timeout ke dependency meningkat,
  • retry pada queue bertambah,
  • error validasi atau deserialisasi baru muncul setelah perubahan kontrak data.

Jika error hanya naik pada node baru atau versi baru, korelasinya dengan deploy menjadi lebih kuat.

Saturation: kapasitas yang diam-diam habis

Saturation menunjukkan apakah resource mendekati batas: CPU, memori, koneksi database, thread pool, pool worker, atau antrean. Ini sering menjadi gejala paling awal sebelum error rate naik.

  • CPU naik dan tetap tinggi setelah deploy dapat menandakan loop, query tidak efisien, atau serialisasi berat.
  • Memori naik terus dapat menandakan kebocoran atau cache yang membesar tak terkendali.
  • Queue depth atau consumer lag meningkat berarti throughput pemrosesan turun, meski API utama masih terlihat sehat.

Anomali log: sinyal yang sering diabaikan

Log warning atau error baru setelah deploy sangat bernilai, terutama bila metrik belum cukup sensitif.

Contoh kueri yang berguna secara umum:

# contoh pseudo-query di sistem log terpusat
service=payments env=prod
| filter level in ["WARN", "ERROR"]
| filter timestamp > deploy_start_time
| group by message, route, exception
| sort count desc

Tujuannya bukan membaca semua log, melainkan menemukan pola baru yang muncul sesudah versi baru aktif.

Kriteria lanjut, tahan, atau rollback

Runbook deployment harus mengubah observasi menjadi keputusan operasional. Tanpa ambang yang jelas, tim cenderung berdebat terlalu lama.

Kapan lanjut

  • Health check lulus di instance baru.
  • Tidak ada kenaikan bermakna pada latency, error rate, atau saturation di jalur kritis.
  • Log anomali tidak menunjukkan pola baru yang relevan.
  • Canary stabil dalam periode observasi yang disepakati.

Kapan tahan dulu

  • Ada kenaikan latency atau warning log, tetapi dampaknya belum konsisten.
  • Gejala hanya muncul di sebagian kecil traffic dan perlu validasi tambahan.
  • Terdapat sinyal konflik konfigurasi, cache, atau konektivitas dependency yang mungkin bukan akibat kode baru semata.

Menahan rollout berarti berhenti menambah traffic, bukan diam tanpa tindakan. Pada fase ini, tim mengumpulkan bukti: bandingkan node lama vs baru, endpoint terpengaruh, dan perubahan resource.

Kapan rollback

  • Error rate naik jelas setelah deploy dan terkait jalur kritis.
  • Latency meningkat cukup besar dan menetap, terutama pada transaksi utama.
  • Queue lag atau saturation menunjukkan penurunan kapasitas yang terus memburuk.
  • Health check gagal atau instance baru tidak stabil.
  • Ada bukti kuat perubahan schema atau kontrak data menyebabkan incompatibility.

Aturan praktis: jika gejala mengarah pada kerusakan progresif dan diagnosis cepat tidak mungkin, rollback biasanya lebih murah daripada investigasi panjang di atas sistem yang terus memburuk.

Rollback yang aman untuk aplikasi, schema, dan worker

Bagian paling berbahaya dari deployment sering bukan deploy itu sendiri, melainkan rollback yang setengah matang. Berikut area yang perlu dipikirkan terpisah.

1. Rollback aplikasi

Rollback aplikasi relatif sederhana jika artefak lama masih tersedia dan deployment bersifat immutable.

  1. Hentikan penambahan traffic ke versi baru.
  2. Arahkan traffic ke versi stabil sebelumnya.
  3. Verifikasi health check, error rate, dan latency pada versi lama.
  4. Pastikan tidak ada node baru yang masih menerima traffic diam-diam.

Kesalahan umum: versi lama aktif kembali, tetapi job scheduler atau worker versi baru masih berjalan dan tetap memproduksi efek samping.

2. Rollback schema database

Rollback schema harus dianggap kasus khusus. Tidak semua migration aman untuk dibalik, terutama jika sudah ada penulisan data dengan format baru.

Pola yang lebih aman adalah expand and contract:

  • Expand: tambahkan kolom/tabel/index baru tanpa merusak pembaca lama.
  • Deploy aplikasi yang bisa membaca/menulis dalam mode kompatibel.
  • Migrasikan penggunaan secara bertahap.
  • Contract: hapus field atau perilaku lama hanya setelah yakin tidak dipakai.

Dengan pola ini, rollback aplikasi tidak langsung berbenturan dengan schema.

Contoh migration yang relatif aman secara konsep:

-- tahap expand
ALTER TABLE orders ADD COLUMN status_v2 TEXT NULL;

-- aplikasi sementara menulis status lama dan status_v2
-- pembaca lama tetap memakai kolom lama

-- tahap contract dilakukan belakangan setelah verifikasi

Yang perlu dihindari saat deploy berisiko:

  • rename kolom yang langsung memutus pembaca lama,
  • drop kolom yang mungkin masih dipakai,
  • migration besar yang mengunci tabel lama sekali jalan tanpa mitigasi.

3. Rollback worker, queue, dan job in-flight

Sistem dengan worker butuh perhatian khusus karena kegagalan sering tertunda. API terlihat sehat, tetapi backlog terus tumbuh.

Langkah aman secara umum:

  1. Pause atau kurangi konsumsi worker versi baru jika diduga sumber masalah.
  2. Pastikan format pesan atau payload masih bisa diproses versi lama.
  3. Rollback worker ke versi stabil.
  4. Monitor retry, dead-letter queue, dan backlog setelah rollback.

Jika versi baru mengubah format event secara tidak kompatibel, rollback aplikasi saja belum cukup. Inilah alasan schema event dan payload queue sebaiknya dirancang kompatibel selama masa transisi.

4. Verifikasi setelah rollback

Rollback belum selesai hanya karena perintah sukses. Verifikasi minimal mencakup:

  • latency kembali ke baseline wajar,
  • error rate turun,
  • saturation stabil,
  • queue lag menurun,
  • log anomali baru berhenti muncul.

Contoh timeline insiden ringan saat deploy

Runbook deployment lebih mudah dipakai jika memuat pola waktu yang realistis. Berikut contoh insiden ringan yang belum menjadi outage penuh.

  1. 10:00 — Deploy dimulai ke 10% traffic canary.
  2. 10:03 — Health check lulus. Tidak ada error besar.
  3. 10:05 — p95 latency endpoint pembayaran naik dibanding baseline. Belum ada alarm kritis.
  4. 10:07 — Log warning baru muncul terkait timeout ke dependency internal pada instance versi baru.
  5. 10:09 — Queue notifikasi mulai tertinggal, menandakan worker juga terdampak.
  6. 10:10 — Keputusan: tahan rollout, jangan naikkan traffic.
  7. 10:14 — Korelasi kuat ditemukan: hanya pod versi baru yang memperlihatkan timeout dan penggunaan koneksi lebih tinggi.
  8. 10:15 — Keputusan: rollback versi aplikasi dan worker.
  9. 10:20 — Metrik mulai kembali normal. Backlog queue masih ada tetapi menurun.
  10. 10:35 — Verifikasi pascarollback selesai. Insiden ditutup sebagai insiden ringan, lanjut ke postmortem singkat.

Hal penting dari timeline seperti ini adalah tim mengambil tindakan saat gejala masih kecil, bukan menunggu error total.

Tindakan pencegahan agar runbook deployment lebih jarang dipakai untuk rollback

Canary deployment

Canary membantu membatasi blast radius. Cocok saat Anda ingin mengamati perilaku versi baru di traffic nyata sebelum rollout penuh.

Pilih canary jika:

  • perubahan menyentuh jalur kritis,
  • risiko interaksi dengan data produksi tinggi,
  • pengujian staging tidak cukup merepresentasikan beban nyata.

Feature flag

Feature flag berguna jika kode baru perlu dirilis tanpa langsung mengaktifkan perilaku baru. Ini memisahkan risiko deploy dari risiko perubahan fitur.

Trade-off-nya: kompleksitas meningkat. Flag harus punya masa hidup jelas; jika dibiarkan terlalu lama, kode menjadi sulit dirawat.

Health check yang bermakna

Health check jangan hanya menjawab “proses hidup”. Minimal bedakan:

  • liveness: proses tidak macet,
  • readiness: instance siap menerima traffic,
  • dependency check terbatas: jika perlu, pastikan dependency kritis tersedia tanpa membuat health endpoint terlalu berat.

Health check yang terlalu dangkal sering membuat instance bermasalah tetap menerima traffic.

Verifikasi pascadeploy

Setelah deploy sukses, lakukan pemeriksaan aktif:

  • uji endpoint kritis,
  • cek dashboard 10–15 menit pertama,
  • lihat log versi baru,
  • verifikasi job terjadwal, queue, dan notifikasi,
  • pastikan metrik bisnis dasar tidak anomali jika tersedia.

Kesalahan umum adalah menganggap “deploy selesai” ketika pipeline hijau, padahal degradasi baru terlihat beberapa menit kemudian.

Template runbook deployment untuk tim kecil

Template berikut cukup ringkas untuk dipakai langsung dan bisa disimpan di repositori internal.

Nama layanan: ____________________
Perubahan: _______________________
Tanggal/waktu deploy: ____________
Operator: ________________________
Reviewer/on-call: ________________
Versi target: ____________________
Versi rollback: __________________

[1] Ruang lingkup perubahan
- Komponen: API / frontend / worker / database / config
- Endpoint atau job kritis yang terdampak:
- Dependency eksternal/internal yang relevan:
- Risiko utama:

[2] Checklist pra-deploy
- CI/build lulus
- Artefak rilis terverifikasi
- Config/secret tersedia
- Dashboard observability siap
- Query log siap
- Migration ditinjau
- Rollback plan ditinjau
- Kanal komunikasi aktif

[3] Strategi rollout
- Metode: full / bertahap / canary
- Persentase awal traffic:
- Durasi observasi per tahap:
- Kriteria naik ke tahap berikutnya:

[4] Sinyal yang dipantau
- Latency: endpoint kritis apa?
- Error rate: kode/jenis error apa?
- Saturation: CPU/memori/koneksi DB/queue lag
- Log: exception atau warning prioritas

[5] Kriteria keputusan
LANJUT jika:
- Health check lulus
- Tidak ada kenaikan bermakna pada metrik kritis
- Log anomali tidak menunjukkan pola baru

TAHAN jika:
- Ada gejala awal tetapi belum konklusif
- Perlu membandingkan node lama vs baru

ROLLBACK jika:
- Error rate naik konsisten
- Latency jalur kritis naik dan menetap
- Queue lag/saturation memburuk
- Health check gagal atau instance tidak stabil

[6] Langkah rollback
- Hentikan kenaikan traffic ke versi baru
- Arahkan traffic ke versi stabil sebelumnya
- Pause/rollback worker jika relevan
- Tinjau status migration/schema
- Verifikasi metrik dan log setelah rollback

[7] Verifikasi pascadeploy / pascarollback
- Smoke test endpoint kritis
- Dashboard 5/10/15 menit
- Queue/backlog normal
- Log anomali menurun/hilang
- Konfirmasi ke kanal komunikasi

[8] Catatan insiden singkat
- Gejala pertama terlihat jam:
- Dampak:
- Keputusan yang diambil:
- Dugaan akar masalah:
- Tindak lanjut:

Postmortem singkat tanpa budaya menyalahkan

Jika terjadi insiden ringan, lakukan postmortem singkat selagi konteks masih segar. Tujuannya bukan mencari siapa yang salah, melainkan memperbaiki sistem kerja dan pengaman teknis.

Pertanyaan yang berguna:

  • Gejala kecil apa yang pertama muncul?
  • Apakah gejala itu sudah tertulis di runbook deployment?
  • Apa yang membuat keputusan tahan atau rollback terlambat/cepat?
  • Apakah observability cukup untuk membedakan aplikasi, schema, atau worker sebagai sumber masalah?
  • Perubahan apa yang bisa membuat rollback lebih aman pada deploy berikutnya?

Output postmortem sebaiknya konkret, misalnya:

  • menambah dashboard queue lag,
  • mengubah migration menjadi bertahap,
  • menambahkan feature flag,
  • memperjelas readiness check,
  • memperbarui template runbook deployment.

Penutup

Runbook deployment yang efektif bukan dokumen panjang berisi semua kemungkinan. Yang lebih penting adalah ia membantu tim mengenali gejala kecil secara sistematis, membaca sinyal observability yang tepat, lalu mengambil keputusan yang terukur sebelum insiden membesar.

Jika Anda memulai dari checklist pra-deploy yang realistis, rollout bertahap, ambang lanjut/tahan/rollback yang jelas, dan rollback yang aman untuk schema serta worker, tim kecil pun bisa menangani deployment dengan jauh lebih tenang. Anggap setiap deploy seperti inspeksi bertahap: lihat gejala, validasi pola, batasi risiko, dan jangan membongkar lebih jauh daripada yang bisa Anda pasang kembali dengan aman.