Runbook deploy vendor binary berbeda dari deploy aplikasi biasa. Saat Anda merilis binary pihak ketiga atau artefak WASM, Anda sering tidak punya kontrol penuh atas proses build, simbol debug, atau detail perubahan internal. Karena itu, strategi yang aman bukan hanya “salin file lalu restart”, tetapi verifikasi artefak, rollout bertahap, observabilitas minimum, dan rollback yang bisa dilakukan dalam menit.

Jika binary baru memicu error di production, tujuan utama Anda adalah membatasi blast radius, memastikan sinyal kegagalan terdeteksi cepat, lalu kembali ke artefak lama yang sudah diketahui stabil. Artikel ini merangkum runbook praktis untuk deploy vendor binary atau WASM dengan aman, termasuk checklist sebelum deploy, canary, health check, metrik/log/trace minimum, gejala insiden umum, langkah isolasi, dan postmortem ringan tanpa mencari kambing hitam.

Mengapa deploy vendor binary perlu perlakuan khusus

Vendor binary dan artefak WASM membawa risiko yang berbeda dibanding kode yang Anda build sendiri:

  • Supply chain risk: artefak bisa berubah, dipublikasikan ulang, atau diambil dari sumber yang tidak Anda kontrol sepenuhnya.
  • Kurang visibilitas: Anda mungkin tidak tahu perubahan ABI, dependency dinamis, perilaku startup, atau kebutuhan resource baru.
  • Sulit di-debug: stack trace bisa terbatas, simbol tidak tersedia, atau log internal minim.
  • Blast radius tinggi: satu binary yang salah dapat memengaruhi seluruh fleet jika rollout tidak bertahap.

Karena itu, praktik minimum yang layak adalah:

  • pin versi artefak secara eksplisit,
  • simpan artefak secara immutable,
  • verifikasi checksum dan provenance,
  • jalankan canary sebelum rollout penuh,
  • siapkan health check dan sinyal rollback otomatis atau manual,
  • catat kejadian deploy agar bisa dikorelasikan dengan metrik dan log.

Prinsip dasar runbook deploy vendor binary

1. Perlakukan artefak sebagai immutable

Jangan pernah mengandalkan nama file generik seperti latest.wasm atau tool-linux-amd64 tanpa identitas versi yang jelas. Simpan artefak dengan penamaan yang mengandung versi dan checksum, misalnya:

vendor-tool/1.4.2/vendor-tool-linux-amd64.sha256-3f2c...bin
vendor-filter/0.9.1/filter-module.sha256-a18b...wasm

Dengan artefak immutable, rollback berarti memilih ulang artefak lama, bukan “mencari file yang semoga masih sama”. Ini juga mengurangi risiko artefak ditimpa diam-diam.

2. Pin versi, jangan ambil langsung dari "latest"

Di CI/CD, referensi ke artefak harus eksplisit. Hindari pola berikut:

curl -L https://vendor.example.com/download/latest/tool -o /usr/local/bin/tool

Lebih aman:

TOOL_VERSION=1.4.2
TOOL_URL="https://artifacts.internal/vendor/tool/${TOOL_VERSION}/tool-linux-amd64"
TOOL_SHA256="3f2c..."

curl -fsSL "$TOOL_URL" -o /tmp/tool
printf '%s  %s\n' "$TOOL_SHA256" /tmp/tool | sha256sum -c -
install -m 0755 /tmp/tool /opt/vendor/tool-${TOOL_VERSION}

Mengapa ini penting: kalau vendor mem-publish ulang file untuk versi yang sama, deployment Anda masih akan gagal di tahap verifikasi checksum, bukan gagal diam-diam di production.

3. Verifikasi checksum dan provenance

Checksum memastikan file yang diterima sama dengan yang diharapkan. Provenance menambah konteks asal artefak: siapa yang membangun, pipeline mana, source revision apa, dan apakah artefak ditandatangani.

Jika vendor menyediakan signature, attestation, atau metadata provenance, verifikasi di pipeline sebelum artefak masuk ke registry internal. Jika tidak tersedia, minimal lakukan:

  • simpan checksum yang sudah ditinjau,
  • catat URL sumber dan waktu pengambilan,
  • mirror artefak ke storage internal,
  • batasi deployment hanya dari mirror internal tersebut.

Prinsip praktis: production sebaiknya hanya menarik artefak dari sumber internal yang sudah lolos verifikasi, bukan langsung dari internet atau bucket vendor.

Checklist sebelum deploy

Checklist ini cocok dipakai sebelum merilis vendor binary atau WASM ke production.

Checklist teknis

  • Versi artefak sudah dipin secara eksplisit.
  • Checksum cocok dengan nilai yang telah disetujui.
  • Provenance atau signature, jika tersedia, sudah diverifikasi.
  • Artefak disimpan di registry atau object storage internal yang immutable.
  • Dependency runtime diketahui: glibc/musl, arsitektur CPU, library dinamis, atau runtime WASM yang digunakan.
  • Konfigurasi kompatibel dengan binary baru, termasuk env var, flag startup, path file, sertifikat, dan izin akses.
  • Health check siap membedakan proses “hidup” vs “siap melayani”.
  • Metrik, log, dan trace minimum tersedia.
  • Rollback path sudah diuji atau setidaknya terdokumentasi langkah demi langkah.
  • Orang yang on-call tahu jadwal deploy dan sinyal sukses/gagal yang harus dipantau.

Checklist operasional

  • Deploy window dipilih saat tim bisa memantau.
  • Blast radius dibatasi: satu node, satu AZ, atau sebagian kecil traffic dulu.
  • Dashboard utama siap: error rate, latency, saturation CPU/memori, restart count, dan queue backlog jika relevan.
  • Annotasi deploy akan ditulis ke sistem observabilitas.
  • Kriteria rollback sudah jelas sebelum deploy dimulai.

Health check, sinyal, dan observabilitas minimum

Untuk Runbook deploy vendor binary, observabilitas tidak harus mewah, tetapi harus cukup untuk menjawab dua pertanyaan: apakah artefak baru sehat? dan jika tidak sehat, apakah rollback memperbaiki keadaan?

Health check minimum

Bedakan tiga level pengecekan:

  • Process check: proses berjalan atau tidak.
  • Readiness check: proses siap menerima request atau job.
  • Functional smoke check: satu operasi penting benar-benar berhasil.

Kesalahan umum adalah mengandalkan process check saja. Binary bisa hidup tetapi gagal membuka file model, gagal load modul WASM, atau timeout saat mengakses dependency eksternal.

Contoh shell health check sederhana:

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

curl -fsS http://127.0.0.1:8080/ready >/dev/null
curl -fsS http://127.0.0.1:8080/healthz >/dev/null
curl -fsS -X POST http://127.0.0.1:8080/smoke \
  -H 'Content-Type: application/json' \
  -d '{"input":"ping"}' | grep -q 'ok'

Untuk artefak WASM, smoke check sebaiknya memanggil jalur eksekusi yang benar-benar memuat dan menjalankan modul, bukan hanya memeriksa runtime host masih aktif.

Metrik minimum yang perlu ada

  • Request/job success rate
  • Error rate per endpoint atau jenis operasi
  • Latency, minimal p95 atau p99 jika tersedia
  • Restart/crash count
  • CPU dan memory usage
  • Queue backlog atau pending work, jika binary memproses job asynchronous
  • Version label pada metrik atau dashboard untuk membedakan artefak lama vs baru

Tanpa label versi, Anda akan sulit membuktikan bahwa kenaikan error memang berkorelasi dengan binary baru.

Log minimum yang perlu dicatat

  • versi artefak, checksum, dan source URI,
  • waktu startup dan argumen penting,
  • gagal load file, modul, sertifikat, atau dependency dinamis,
  • error parsing input atau protocol mismatch,
  • resource pressure seperti OOM, timeout, atau connection reset.

Jika memungkinkan, tulis satu log event saat startup seperti:

{
  "event": "artifact_loaded",
  "artifact_type": "wasm",
  "artifact_version": "0.9.1",
  "sha256": "a18b...",
  "source": "s3://artifacts/vendor-filter/0.9.1/",
  "instance": "api-17"
}

Trace minimum

Untuk sistem yang sudah memakai distributed tracing, cukup pastikan request yang melewati binary baru tetap menghasilkan trace end-to-end. Anda tidak perlu menambah instrumentasi mendalam di binary vendor jika tidak memungkinkan. Yang penting adalah bisa melihat apakah latency atau error melonjak setelah request masuk ke komponen yang memakai artefak baru.

Strategi rollout aman: canary lalu bertahap

Mulai dari satu unit kecil

Canary terbaik adalah deploy ke unit terkecil yang tetap representatif, misalnya:

  • satu pod atau satu VM,
  • satu availability zone,
  • satu shard non-kritis,
  • 1-5% traffic jika load balancer mendukung weighted routing.

Tujuannya bukan hanya “tes cepat”, tetapi memaksa sistem menunjukkan perilaku nyata di bawah traffic production tanpa membahayakan seluruh fleet.

Kriteria lanjut atau berhenti

Sebelum deploy, tetapkan aturan sederhana:

  • lanjut ke 10-25% bila health check lulus dan tidak ada kenaikan error yang bermakna,
  • tahan di canary bila sinyal belum jelas,
  • rollback segera bila error rate naik, latency melonjak, crash loop muncul, atau smoke check gagal.

Hindari keputusan berbasis intuisi semata. Bahkan aturan manual sederhana lebih baik daripada “kita lihat nanti”.

Contoh alur rollout

  1. Deploy artefak baru ke 1 instance canary.
  2. Jalankan smoke test otomatis.
  3. Pantau 10-15 menit atau sejumlah request minimum yang relevan.
  4. Jika sehat, naikkan ke 10% traffic atau satu subset node.
  5. Pantau lagi metrik inti dan log error.
  6. Jika tetap sehat, lanjut rollout penuh bertahap.
  7. Tulis annotasi deploy di dashboard atau incident timeline.

Contoh runbook deploy vendor binary

Bagian ini sengaja dibuat operasional agar bisa dipakai sebagai template.

Tujuan

Merilis vendor binary atau artefak WASM ke production dengan risiko rendah dan rollback cepat.

Prasyarat

  • Artefak sudah tersedia di storage internal.
  • Checksum dan provenance sudah diverifikasi.
  • Versi target dan versi rollback terakhir diketahui.
  • Dashboard observabilitas siap.
  • Akses untuk deploy dan rollback tersedia.

Langkah deploy

  1. Catat baseline

    Simpan snapshot metrik 15-30 menit terakhir: error rate, latency, throughput, memory, CPU, restart count.

  2. Verifikasi artefak
    ARTIFACT=/opt/staging/vendor-tool-1.4.2
EXPECTED_SHA256=3f2c...
printf '%s  %s\n' "$EXPECTED_SHA256" "$ARTIFACT" | sha256sum -c -
  3. Deploy ke canary

    Update satu pod/VM/instance terlebih dahulu. Pastikan routing traffic ke canary terbatas.

  4. Jalankan smoke test

    Periksa startup, readiness, dan satu jalur fungsi inti.

  5. Pantau sinyal minimum
    • error 5xx atau failure job,
    • latency meningkat tajam,
    • crash loop atau restart,
    • OOM, timeout, atau connection reset,
    • anomali log yang hanya muncul pada versi baru.
  6. Naikkan rollout bertahap

    Jika canary sehat, lanjutkan ke subset kecil berikutnya. Jangan lompat langsung ke 100% bila binary ini menyentuh jalur kritis.

  7. Selesaikan rollout

    Setelah seluruh fleet diperbarui, terus pantau untuk window singkat pascadeploy. Sebagian bug hanya muncul saat concurrency atau volume tertentu tercapai.

Kriteria rollback

  • smoke check gagal,
  • readiness gagal stabil,
  • error rate naik jelas dibanding baseline,
  • latency memburuk dan memengaruhi SLA internal,
  • terjadi crash, OOM, atau kebocoran resource,
  • muncul error baru yang mengarah ke incompatibility binary/runtime/config.

Langkah rollback cepat

  1. Hentikan rollout lebih lanjut.
  2. Alihkan traffic dari canary atau subset yang terdampak.
  3. Re-deploy artefak versi terakhir yang diketahui sehat.
  4. Pastikan instance lama kembali lulus readiness dan smoke check.
  5. Konfirmasi metrik kembali ke baseline atau mendekati baseline.
  6. Simpan bukti insiden: log startup, log error, checksum artefak, instance terdampak, waktu kejadian, perubahan konfigurasi terkait.

Contoh pseudo-command rollback:

PREV_VERSION=1.4.1
TARGET=/opt/vendor/tool-${PREV_VERSION}
ln -sfn "$TARGET" /opt/vendor/current
systemctl restart vendor-tool
./healthcheck.sh

Jika Anda memakai container image, prinsipnya sama: rollback ke image digest lama, bukan sekadar tag lama yang mungkin sudah berubah.

Gejala insiden umum dan langkah isolasi

1. Proses hidup, tetapi readiness gagal

Gejala: service restart terus, pod tidak pernah ready, atau load balancer tidak mengirim traffic.

Penyebab umum:

  • binary butuh file atau secret yang tidak ada,
  • port berubah,
  • startup lebih lambat dari timeout health check,
  • modul WASM gagal dimuat saat init.

Isolasi:

  1. Lihat log startup dan stderr.
  2. Jalankan binary secara lokal di environment yang mirip.
  3. Periksa path file, permission, dan env var.
  4. Naikkan timeout startup sementara hanya jika akar masalah memang startup lambat, bukan hang.

2. Error rate naik hanya di node baru

Gejala: 5xx, job failure, atau parse error hanya muncul pada instance canary.

Penyebab umum:

  • perubahan format input/output,
  • incompatibility ABI atau library dinamis,
  • perbedaan arsitektur CPU atau fitur instruksi,
  • binary baru lebih ketat memvalidasi data.

Isolasi:

  1. Bandingkan request yang gagal di versi baru vs versi lama.
  2. Periksa apakah semua host benar-benar homogen.
  3. Jalankan sample input yang sama ke dua versi.
  4. Jika hasil berbeda, rollback dulu lalu investigasi lebih lanjut.

3. Latency melonjak tanpa banyak error

Gejala: request tetap sukses, tetapi response sangat lambat atau queue backlog naik.

Penyebab umum:

  • algoritma internal berubah,
  • modul WASM lebih mahal dieksekusi,
  • ada fallback ke jalur lambat,
  • binary baru memicu contention CPU atau I/O.

Isolasi:

  1. Bandingkan CPU, memory, dan saturation sebelum/sesudah deploy.
  2. Lihat trace atau timing log di jalur yang memakai binary tersebut.
  3. Turunkan traffic canary untuk memastikan korelasi.
  4. Rollback jika latency mengganggu SLA atau menyebabkan antrian menumpuk.

4. Crash atau OOM setelah beberapa menit

Gejala: canary awalnya sehat, lalu restart atau mati setelah menerima beban.

Penyebab umum:

  • memory leak,
  • ukuran input tertentu memicu alokasi besar,
  • konfigurasi limit terlalu rendah untuk versi baru,
  • bug concurrency yang hanya muncul pada throughput tertentu.

Isolasi:

  1. Korelasikan waktu crash dengan pola traffic.
  2. Periksa OOM killer, exit code, dan memory graph.
  3. Uji ulang dengan traffic terbatas jika aman.
  4. Jangan lanjut rollout walau smoke test awal lulus.

Gate CI/CD yang sebaiknya ada

Runbook operasional akan lebih efektif jika pipeline sudah menahan kesalahan paling umum sebelum artefak sampai ke production.

Gate minimum

  • Checksum wajib cocok: deploy gagal bila hash berbeda.
  • Version pin wajib: blokir penggunaan latest atau tag mutable.
  • Sumber artefak terbatas: hanya boleh dari registry internal.
  • Smoke test di environment pre-prod: minimal memuat binary/WASM dan mengeksekusi satu operasi inti.
  • Kebijakan approval: artefak vendor baru butuh review tambahan jika belum pernah dipakai.
  • Policy rollback tersedia: pipeline tahu versi terakhir yang sehat.

Contoh pemeriksaan sederhana di CI

set -eu

ARTIFACT_URL="$1"
EXPECTED_SHA256="$2"

curl -fsSL "$ARTIFACT_URL" -o artifact.bin
printf '%s  %s\n' "$EXPECTED_SHA256" artifact.bin | sha256sum -c -

# Gagal jika referensi mutable terdeteksi
case "$ARTIFACT_URL" in
  *latest*|*:latest*)
    echo "Ref mutable tidak diizinkan"
    exit 1
    ;;
esac

Ini sederhana, tetapi efektif mencegah dua kelas masalah paling umum: artefak berubah dan referensi yang tidak reproducible.

Postmortem ringan tanpa menyalahkan individu

Kalau deploy gagal, postmortem tidak perlu panjang, tetapi harus cukup untuk mencegah pengulangan. Fokusnya adalah bagaimana sistem memungkinkan kegagalan lolos, bukan siapa yang menekan tombol deploy.

Struktur postmortem ringkas

  • Ringkasan: apa yang di-deploy, kapan, dan dampaknya.
  • Timeline: waktu deploy, deteksi, rollback, pemulihan.
  • Gejala: error rate, latency, crash, readiness failure, atau lainnya.
  • Akar masalah teknis: misalnya checksum benar tetapi ada incompatibility runtime, atau smoke test tidak mencakup jalur penting.
  • Gap sistem: observabilitas kurang, gate CI/CD belum ada, rollback terlalu manual, canary terlalu besar.
  • Tindakan pencegahan: perubahan kecil yang konkret dan dapat ditindaklanjuti.

Contoh temuan dan perbaikan

  • Temuan: binary vendor baru memerlukan library dinamis yang tidak ada pada sebagian host.
    Perbaikan: tambah pemeriksaan dependency runtime di pre-prod dan validasi homogenitas host.
  • Temuan: smoke test hanya memeriksa HTTP 200, tidak benar-benar mengeksekusi modul WASM.
    Perbaikan: ubah smoke test agar memanggil jalur eksekusi nyata.
  • Temuan: rollback lambat karena artefak lama tidak tersimpan rapi.
    Perbaikan: gunakan artefak immutable dan alias versi saat deploy.
  • Temuan: deploy langsung ke 50% traffic tanpa canary kecil.
    Perbaikan: tetapkan kebijakan default rollout bertahap.

Postmortem yang baik menghasilkan perubahan pada sistem: checklist lebih baik, gate pipeline baru, health check yang lebih realistis, atau mekanisme rollback yang lebih cepat.

Rekomendasi praktis yang paling berdampak

Jika Anda belum punya banyak proses, mulai dari lima hal ini:

  1. Pin versi artefak dan larang referensi mutable.
  2. Verifikasi checksum sebelum artefak dipakai di environment mana pun.
  3. Simpan artefak secara immutable di registry atau object storage internal.
  4. Deploy canary kecil dengan smoke test yang benar-benar menjalankan fungsi inti.
  5. Siapkan rollback satu langkah ke versi terakhir yang sehat.

Kelima praktik ini tidak menghilangkan semua risiko vendor binary atau WASM, tetapi secara nyata menurunkan kemungkinan insiden besar dan mempercepat pemulihan saat ada masalah.

Penutup

Deploy vendor binary atau artefak WASM ke production aman bukan soal percaya penuh pada vendor, melainkan soal membangun pagar pengaman di sekitar artefak yang Anda tidak kontrol sepenuhnya. Runbook deploy vendor binary yang baik harus mencakup verifikasi checksum dan provenance, rollout bertahap dengan canary, health check yang benar-benar bermakna, sinyal observabilitas minimum, rollback cepat, dan postmortem ringan yang mendorong perbaikan sistem.

Jika Anda hanya mengambil satu pelajaran, ambil ini: jangan pernah membuat rollback lebih sulit daripada deploy. Pada artefak vendor, kemampuan kembali ke versi terakhir yang sehat sering lebih berharga daripada optimisasi pipeline yang terlalu canggih tetapi sulit dioperasikan saat insiden.