Runbook deploy dan rollback yang baik bukan dokumen panjang dengan istilah rumit, melainkan panduan operasional yang bisa diikuti dengan cepat saat sistem sedang bermasalah. Tujuannya sederhana: mengurangi kebingungan, mempercepat keputusan, dan membuat langkah eksekusi konsisten antar anggota tim.

Masalah yang sering terjadi bukan karena tim tidak punya dokumentasi, tetapi karena isi runbook terlalu abstrak. Kalimat seperti "validasi integritas layanan pasca-rilis" terdengar rapi, tetapi tidak membantu ketika engineer harus bertindak dalam lima menit. Saat insiden, instruksi harus konkret: apa yang dicek, perintah apa yang dijalankan, indikator apa yang dianggap gagal, dan kapan rollback dilakukan.

Artikel ini membahas struktur runbook yang sederhana, checklist sebelum deploy, observability dasar yang wajib ada, kriteria rollback yang jelas, template postmortem singkat, dan tindakan pencegahan agar insiden serupa tidak terulang.

Mengapa runbook harus sederhana dan tidak ambigu

Runbook dipakai dalam kondisi normal maupun saat tekanan tinggi. Di situ, bahasa yang "terdengar pintar" justru berbahaya karena bisa ditafsirkan berbeda oleh tiap orang. Prinsip dasarnya:

  • Satu langkah = satu tindakan yang bisa dieksekusi.
  • Sebutkan alat dan sumber data yang dipakai. Misalnya dashboard, log aggregator, atau perintah CLI.
  • Tetapkan hasil yang diharapkan. Contoh: error rate tetap di bawah ambang tertentu.
  • Tentukan keputusan berikutnya. Jika gagal, lanjut ke rollback; jika sukses, lanjut verifikasi berikutnya.

Runbook bukan tempat untuk menjelaskan semua teori sistem. Yang dibutuhkan operator saat deploy adalah instruksi yang ringkas, dapat diperiksa, dan minim interpretasi.

Contoh langkah yang buruk vs versi yang lebih sederhana

Buruk:

Lakukan validasi layanan secara menyeluruh untuk memastikan stabilitas rilis sebelum eksposur trafik penuh.

Lebih sederhana:

Setelah deploy, buka dashboard API. Periksa selama 10 menit:
1) error rate tidak naik tajam,
2) latency p95 tidak memburuk dibanding sebelum deploy,
3) tidak ada lonjakan error database,
4) endpoint /health dan 3 endpoint utama merespons normal.
Jika salah satu gagal, hentikan rollout dan mulai rollback.

Buruk:

Pastikan migrasi database aman.

Lebih sederhana:

Periksa apakah migrasi hanya menambah kolom/tabel, bukan menghapus atau mengubah tipe kolom yang sedang dipakai aplikasi lama. Jika migrasi bersifat destruktif, pisahkan ke rilis terpisah dan jangan dijalankan bersamaan dengan deploy aplikasi.

Struktur runbook deploy dan rollback yang praktis

Struktur yang baik memudahkan engineer menemukan informasi tanpa membaca dokumen dari awal. Format di bawah cukup sederhana untuk sebagian besar layanan backend atau web application.

1. Informasi dasar layanan

  • Nama layanan
  • Pemilik layanan atau tim penanggung jawab
  • Repository atau pipeline yang dipakai
  • Lingkungan target: staging, production
  • Dependensi penting: database, cache, queue, external API

2. Prasyarat deploy

  • Akses ke CI/CD, server, cluster, atau platform deploy
  • Akses ke dashboard metrics, log, dan alert
  • Akses ke fitur rollback atau artefak rilis sebelumnya
  • Persetujuan perubahan jika organisasi mewajibkan approval

3. Langkah deploy

Buat urutannya eksplisit. Hindari frasa seperti "deploy seperti biasa". Contoh urutan:

  1. Pastikan branch atau commit yang akan dirilis sudah disetujui.
  2. Pastikan pipeline test terakhir lulus.
  3. Periksa apakah ada migrasi database dan nilai risikonya.
  4. Mulai deploy ke production melalui pipeline.
  5. Verifikasi instance baru sehat.
  6. Pantau metrik dan log selama jendela observasi.
  7. Jika hasil normal, selesaikan rollout. Jika tidak, rollback.

4. Verifikasi pascadeploy

  • Status health check
  • Error rate aplikasi
  • Latency endpoint utama
  • Throughput atau request rate
  • Error database atau cache
  • Log error baru yang muncul setelah waktu deploy
  • Smoke test fitur utama

5. Kriteria rollback

Bagian ini wajib objektif. Jangan menulis "rollback jika terasa bermasalah". Tentukan sinyal yang jelas, misalnya:

  • Health check gagal di instance baru.
  • Error rate meningkat dan tidak turun selama beberapa menit observasi.
  • Lonjakan 5xx pada endpoint kritis.
  • Query database gagal karena skema tidak kompatibel.
  • Worker queue gagal memproses job penting setelah rilis.
  • Bug fungsional pada alur bisnis inti, misalnya checkout atau login.

6. Langkah rollback

Rollback harus sama jelasnya dengan deploy. Minimal berisi:

  1. Identifikasi versi stabil terakhir.
  2. Jalankan rollback melalui pipeline atau artefak sebelumnya.
  3. Verifikasi layanan kembali sehat.
  4. Pantau metrik dan log hingga kembali ke baseline.
  5. Catat waktu rollback dan gejala yang diamati.

7. Kontak dan eskalasi

  • On-call engineer
  • PIC layanan
  • Tim database jika migrasi berisiko
  • Tim infrastruktur jika ada isu jaringan, node, atau load balancer

Checklist sebelum deploy yang benar-benar berguna

Checklist yang baik harus singkat, tetapi cukup untuk mencegah kesalahan umum. Berikut contoh yang realistis.

Checklist sebelum deploy

  • Perubahan sudah direview dan branch target benar.
  • Semua test otomatis yang wajib sudah lulus.
  • Konfigurasi baru sudah tersedia di environment target.
  • Feature flag sudah disiapkan jika dipakai.
  • Migrasi database sudah ditinjau dan dinilai aman untuk rilis ini.
  • Versi sebelumnya tersedia untuk rollback.
  • Dashboard metrics dan log sudah dibuka sebelum deploy dimulai.
  • Jendela deploy tidak bertabrakan dengan pekerjaan berisiko lain.
  • Stakeholder internal tahu bahwa deploy sedang berlangsung jika memang perlu notifikasi.

Kenapa checklist ini bekerja

Checklist mencegah tim mengandalkan ingatan saat kondisi sibuk. Banyak insiden bukan berasal dari bug aplikasi semata, melainkan dari hal operasional yang terlupa: environment variable belum ada, migrasi tidak kompatibel, atau dashboard belum disiapkan sehingga gejala telat terlihat.

Observability dasar yang wajib dipantau saat deploy

Anda tidak perlu sistem observability yang kompleks agar runbook berguna. Yang penting adalah sinyal minimum yang cukup untuk menjawab satu pertanyaan: apakah rilis ini membuat sistem memburuk?

Metrik minimum

  • Error rate: apakah jumlah request gagal naik setelah deploy.
  • Latency: terutama p95 atau indikator latensi yang biasa dipakai tim.
  • Traffic atau throughput: membantu membedakan antara masalah aplikasi dan perubahan volume trafik.
  • Resource usage: CPU, memori, restart container, atau saturation worker jika relevan.
  • Dependency errors: error ke database, cache, message broker, atau external API.

Log minimum

  • Log error aplikasi
  • Log startup atau deployment event
  • Log migrasi database jika ada
  • Log worker atau queue consumer untuk job penting

Verifikasi yang sebaiknya dilakukan

  1. Beri penanda waktu deploy pada dashboard atau catat jam deploy secara jelas.
  2. Bandingkan 5-15 menit sebelum dan sesudah deploy, bukan hanya melihat angka saat ini.
  3. Cari error baru yang muncul tepat setelah rilis dimulai.
  4. Uji alur bisnis utama secara manual atau dengan smoke test otomatis.

Jika tim sudah memakai tracing, itu sangat membantu untuk melihat request yang melambat setelah rilis. Tetapi untuk runbook dasar, metrics dan logs yang baik sudah cukup.

Contoh smoke test sederhana

# Contoh verifikasi endpoint dasar setelah deploy
curl -fsS https://service.example.com/health
curl -fsS https://service.example.com/api/products?limit=1
curl -fsS -X POST https://service.example.com/api/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"***"}'

Contoh di atas bukan untuk menggantikan test otomatis, tetapi untuk memastikan endpoint penting benar-benar merespons setelah rilis.

Kriteria rollback yang jelas dan mudah diputuskan

Banyak tim terlambat rollback karena tidak punya batas keputusan yang disepakati. Akibatnya, engineer terus mencoba memperbaiki sambil layanan tetap rusak. Runbook harus menyatakan kapan rollback menjadi pilihan utama.

Kapan sebaiknya rollback

  • Gangguan muncul segera setelah deploy dan korelasinya kuat.
  • Masalah memengaruhi fitur inti atau banyak pengguna.
  • Perbaikan cepat tidak jelas atau tidak bisa dilakukan dengan aman dalam waktu singkat.
  • Perubahan bisa dikembalikan tanpa merusak data atau kompatibilitas.

Kapan rollback tidak selalu cukup

  • Migrasi database sudah bersifat destruktif.
  • Data sudah ditulis dengan format baru yang tidak kompatibel ke versi lama.
  • Masalah ada pada dependency eksternal, bukan pada rilis aplikasi.

Ini sebabnya strategi deploy yang aman sering memisahkan perubahan aplikasi dari perubahan skema destruktif. Praktik umum yang lebih aman adalah expand-and-contract: tambahkan struktur baru dulu, buat aplikasi kompatibel dengan skema lama dan baru, baru hapus bagian lama di rilis terpisah.

Contoh bagian rollback di runbook

Jika salah satu kondisi berikut terjadi dalam 10 menit pertama setelah deploy:
- health check gagal di instance baru,
- error 5xx meningkat dan tidak kembali normal,
- login atau checkout gagal,
- worker job pembayaran gagal,
maka lakukan rollback ke release sebelumnya.

Langkah rollback:
1. Buka pipeline deploy.
2. Pilih release stabil terakhir.
3. Jalankan rollback.
4. Verifikasi /health dan 3 endpoint utama.
5. Pantau dashboard error rate dan latency sampai kembali normal.
6. Catat waktu mulai, waktu rollback, dan gejala utama.

Template runbook deploy dan rollback yang bisa langsung dipakai

Berikut template ringkas yang bisa Anda adaptasi.

Nama layanan: ________
Pemilik: ________
Repository/Pipeline: ________
Environment: production
Dependensi penting: database, redis, queue, payment API

Prasyarat:
- Akses ke pipeline deploy
- Akses ke dashboard metrics dan logs
- Release sebelumnya tersedia untuk rollback

Checklist sebelum deploy:
- PR/review selesai
- Test wajib lulus
- Config/env sudah tersedia
- Migrasi database ditinjau
- Dashboard monitoring dibuka

Langkah deploy:
1. Pastikan commit/tag yang akan dirilis benar.
2. Jalankan deploy melalui pipeline.
3. Tunggu instance baru sehat.
4. Pantau metrics dan logs selama 10 menit.
5. Jalankan smoke test endpoint utama.
6. Jika normal, selesaikan rollout.
7. Jika tidak normal, rollback.

Pantauan pascadeploy:
- Error rate
- Latency p95
- Status /health
- Error database/cache/queue
- Log error baru

Kriteria rollback:
- Health check gagal
- Lonjakan 5xx
- Endpoint inti gagal
- Error dependency naik setelah deploy

Langkah rollback:
1. Pilih release stabil terakhir.
2. Jalankan rollback.
3. Verifikasi health check dan endpoint utama.
4. Pantau metrics sampai stabil.
5. Catat insiden singkat.

Eskalasi:
- On-call engineer: ________
- PIC layanan: ________
- Tim database: ________

Postmortem ringan: cukup singkat, tetapi harus menghasilkan tindakan

Setelah insiden selesai, jangan berhenti di kalimat "sudah di-rollback". Anda butuh postmortem ringan agar tim belajar tanpa membuat proses menjadi berat. Untuk insiden skala kecil hingga menengah, format singkat sudah cukup selama fokus pada fakta dan perbaikan.

Template postmortem singkat

  • Ringkasan: apa yang terjadi dan layanan apa yang terdampak.
  • Dampak: fitur yang terganggu, durasi, dan siapa yang terpengaruh.
  • Timeline: jam deploy, gejala pertama, deteksi, rollback/perbaikan, pulih.
  • Akar masalah: perubahan apa yang memicu insiden.
  • Apa yang berjalan baik: misalnya alert cepat, rollback lancar.
  • Apa yang kurang: misalnya runbook tidak jelas, smoke test tidak mencakup kasus tertentu.
  • Tindakan pencegahan: item konkret dengan PIC dan tenggat waktu.

Contoh postmortem ringan

Ringkasan:
Deploy layanan API menyebabkan endpoint login gagal untuk sebagian pengguna.

Dampak:
Login gagal selama 12 menit di production.

Timeline:
- 10:02 deploy dimulai
- 10:05 error login meningkat
- 10:07 on-call menerima alert
- 10:10 diputuskan rollback
- 10:14 rollback selesai
- 10:17 metrik kembali normal

Akar masalah:
Perubahan query membutuhkan kolom baru, tetapi migrasi belum dijalankan di semua environment yang relevan.

Yang berjalan baik:
- Alert error rate aktif
- Rollback tersedia dan cepat dijalankan

Yang kurang:
- Checklist deploy tidak memverifikasi kesiapan skema database
- Smoke test tidak mencakup login

Tindakan pencegahan:
- Tambahkan pemeriksaan migrasi pada checklist deploy
- Tambahkan smoke test login ke runbook
- Pisahkan perubahan skema berisiko ke rilis terpisah

Tindakan pencegahan agar insiden serupa tidak terulang

Runbook yang baik tidak hanya membantu respons insiden, tetapi juga memperbaiki cara tim merilis perubahan berikutnya. Beberapa tindakan pencegahan yang paling bernilai biasanya sederhana.

1. Gunakan bahasa operasional, bukan bahasa abstrak

Ganti instruksi umum dengan tindakan yang bisa dilakukan siapa saja yang punya akses yang tepat. Jika sebuah langkah masih bisa ditafsirkan dua cara, langkah itu belum cukup baik.

2. Pisahkan perubahan berisiko tinggi

Jangan gabungkan deploy aplikasi, migrasi skema destruktif, perubahan cache key, dan perubahan queue sekaligus jika tidak perlu. Semakin banyak komponen berubah bersamaan, semakin sulit mencari penyebab insiden.

3. Siapkan rollback sebelum deploy, bukan sesudah gagal

Pastikan artefak versi sebelumnya tersedia, pipeline rollback dikenali, dan tim tahu apakah rollback aman terhadap perubahan data.

4. Tambahkan smoke test untuk alur bisnis inti

Health check saja tidak cukup. Endpoint sehat tidak menjamin login, checkout, upload, atau pembayaran benar-benar bekerja.

5. Tinjau runbook setelah insiden atau setelah perubahan arsitektur

Runbook yang tidak diperbarui akan cepat usang. Jika pipeline berubah, dashboard berpindah, atau dependensi baru ditambahkan, dokumen juga harus diperbarui.

6. Latih runbook pada kondisi normal

Cobalah deploy rutin dengan mengikuti runbook secara literal. Jika ada langkah yang membuat engineer bertanya "maksudnya apa?", berarti langkah itu masih terlalu kabur.

Kesalahan umum saat menulis runbook

  • Terlalu banyak jargon: sulit dipahami saat insiden.
  • Tidak menyebutkan sumber verifikasi: misalnya metrik apa, dashboard mana, atau log apa yang harus dibuka.
  • Tidak ada kriteria rollback: tim ragu mengambil keputusan.
  • Tidak mempertimbangkan database: padahal banyak rollback gagal karena incompatibility skema.
  • Terlalu panjang dan naratif: sulit dipakai sebagai panduan operasional cepat.
  • Tidak pernah diuji: dokumen tampak benar, tetapi tidak berguna saat dipakai.

Penutup

Runbook deploy dan rollback yang efektif tidak harus panjang atau rumit. Yang terpenting adalah setiap langkah mudah diikuti, hasil yang diharapkan jelas, sinyal observability minimal tersedia, dan keputusan rollback bisa diambil tanpa debat panjang.

Jika Anda ingin mulai hari ini, lakukan tiga hal dulu: rapikan checklist sebelum deploy, tetapkan kriteria rollback yang objektif, dan ubah semua instruksi abstrak menjadi langkah operasional yang sederhana. Dalam banyak kasus, itu sudah cukup untuk mengurangi kekacauan saat insiden berikutnya datang.